Merge pull request #460 from cianwilson/coupled_bcs

Allow the boundary conditions of scalar fields to be coupled

.github/workflows/main.yml

@@ -74,6 +74,10 @@ jobs:
         cd "$GITHUB_WORKSPACE"
         sh ./tests/custom_reference/run_test.sh
 
+        # coupled bc test
+        cd "$GITHUB_WORKSPACE"
+        sh ./tests/coupled_bcs/run_test.sh
+        
         git diff > changes.diff
         git diff --exit-code --name-only
 

CHANGELOG.md

@@ -10,6 +10,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## [Unreleased]
 ### Added
 
+- Allow the boundary conditions of scalar fields (both the thermal temperature/entropy field and active scalar fields) to be linearly coupled together.  This is documented in the "Under Development" section of the User Guide and has an example test. \[Cian Wilson; 6-21-2024; [#460](https://github.com/geodynamics/Rayleigh/pull/460)\]
+
 - The documentation for solving for active and passive scalar fields has been expanded in the "Under Development" section of the User Guide. \[Cian Wilson; 6-20-2024; [#541](https://github.com/geodynamics/Rayleigh/pull/541)\]
 
 - A docker image for Stampede3 and Frontera (TACC) has been added to the repository.   \[Rene Gassmoeller; 6-20-2024; [#402](https://github.com/geodynamics/Rayleigh/pull/402)\]

doc/source/Namelist_Definitions/boundary_conditions_namelist.txt

@@ -1,15 +1,15 @@
 **fix_tvar_top**  
-  Logical flag indicating whether thermal variable (T,S) should be fixed on the upper boundary.  Default = .true.
+  Logical flag indicating whether thermal variable (T,S) should be fixed on the upper boundary.  Default = .false.
 **fix_tvar_bottom**
-  Logical flag indicating whether thermal variable (T,S) should be fixed on the lower boundary.  Default = .true.
+  Logical flag indicating whether thermal variable (T,S) should be fixed on the lower boundary.  Default = .false.
 **fix_dtdr_top**  
   Logical flag indicating whether the radial derivative of thermal variable (T,S) should be fixed on the upper boundary.  Default = .false.
 **fix_dtdr_bottom**  
   Logical flag indicating whether the radial derivative of thermal variable (T,S) should be fixed on the lower boundary.  Default = .false.
 **T_top**
   Value of thermal variable (T,S) at the upper boundary.  Default = 0.
 **T_bottom**
-  Value of thermal variable (T,S) at the lower boundary.  Default = 1.  
+  Value of thermal variable (T,S) at the lower boundary.  Default = 0.  
 **dTdr_top**
   Value of radial derivative of thermal variable (T,S) at the upper boundary.  Default = 0.
 **dTdr_bottom**

doc/source/User_Guide/coupled_bcs.txt

@@ -0,0 +1,181 @@
+Rayleigh can couple the values and gradients of scalar fields (including the temperature/entropy, :math:`\Theta`, and active,
+:math:`\chi_{a_i}`, scalar fields) at the
+boundaries through this initial implementation of coupled boundary conditions.
+
+These boundary conditions take the form:
+
+.. math::
+   :label: coupled_bcs_T
+
+   \Theta = b_{\Theta,\Theta} + b_{\Theta,\frac{\partial \Theta}{\partial r}}\frac{\partial \Theta}{\partial r} \
+       + \sum_{j} b_{\Theta,\chi_{a_j}} \chi_{a_j} \
+       + \sum_{j} b_{\Theta,\frac{\partial\chi_{a_j}}{\partial r}} \frac{\partial\chi_{a_j}}{\partial r}
+
+for coupling temperature/entropy to its gradient and/or to other scalar fields,
+
+.. math::
+   :label: coupled_bcs_dTdr
+
+   \frac{\partial \Theta}{\partial r} = b_{\frac{\partial \Theta}{\partial r},\frac{\partial \Theta}{\partial r}} + b_{\frac{\partial \Theta}{\partial r},\Theta}\Theta \
+       + \sum_{j} b_{\frac{\partial \Theta}{\partial r},\chi_{a_j}} \chi_{a_j} \
+       + \sum_{j} b_{\frac{\partial \Theta}{\partial r},\frac{\partial\chi_{a_j}}{\partial r}} \frac{\partial\chi_{a_j}}{\partial r}
+
+for coupling the derivative of temperature/entropy to its value and/or to other scalar fields,
+
+.. math::
+   :label: coupled_bcs_chia
+
+   \chi_{a_i} = b_{\chi_{a_i},\chi_{a_i}} \
+       + b_{\chi_{a_i},\Theta}\Theta \
+       + b_{\chi_{a_i},\frac{\partial \Theta}{\partial r}}\frac{\partial \Theta}{\partial r} \
+       + \sum_{j (j \ne i)} b_{\chi_{a_i},\chi_{a_j}} \chi_{a_j} \
+       + \sum_{j} b_{\chi_{a_i},\frac{\partial\chi_{a_j}}{\partial r}} \frac{\partial\chi_{a_j}}{\partial r}
+
+for coupling active scalar i to its gradient and/or to other scalar fields including temperature/entropy, and finally
+
+.. math::
+   :label: coupled_bcs_dchiadr
+
+   \frac{\partial \chi_{a_i}}{\partial r} = b_{\frac{\partial \chi_{a_i}}{\partial r},\frac{\partial \chi_{a_i}}{\partial r}} \
+       + b_{\frac{\partial\chi_{a_i}}{\partial r},\Theta}\Theta \
+       + b_{\frac{\partial\chi_{a_i}}{\partial r},\frac{\partial \Theta}{\partial r}}\frac{\partial \Theta}{\partial r} \
+       + \sum_{j} b_{\frac{\partial\chi_{a_i}}{\partial r},\chi_{a_j}} \chi_{a_j} \
+       + \sum_{j (j \ne i)} b_{\frac{\partial\chi_{a_i}}{\partial r},\frac{\partial\chi_{a_j}}{\partial r}} \frac{\partial\chi_{a_j}}{\partial r}
+
+for coupling the gradient of active scalar i to its value and/or to other scalar fields including temperature/entropy.
+
+The values of the :math:`b_{i,i}` terms can be constant or spatially varying.  The values of the :math:`b_{i,j}` coefficients are constant.  All values can be set using options in the boundary conditions namespace.
+
+Setup
+^^^^^
+
+Boundary conditions
+*******************
+
+Model parameters for the scalar fields follow the same convention as temperature but using the prefix `chi_a` or `chi_p` for active and passive
+scalars respectively.
+
+**couple_tvar_top**  
+  Logical flag indicating whether thermal variable (T,S) should be coupled to other scalar fields or their gradients on the upper boundary.  Default = .false.
+**couple_tvar_bottom**  
+  Logical flag indicating whether thermal variable (T,S) should be coupled to other scalar fields or their gradients on the lower boundary.  Default = .false.
+
+**couple_dtdr_top**  
+  Logical flag indicating whether radial gradient of thermal variable (T,S) should be coupled to other scalar fields or their gradients on the upper boundary.  Default = .false.
+**couple_dtdr_bottom**  
+  Logical flag indicating whether radial gradient of thermal variable (T,S) should be coupled to other scalar fields or their gradients on the lower boundary.  Default = .false.
+
+**couple_chivar_a_top**  
+  Logical flag indicating whether active scalar i should be coupled to other scalar fields or their gradients on the upper boundary.  Default = .false.
+**couple_chivar_a_bottom**  
+  Logical flag indicating whether active scalar i should be coupled to other scalar fields or their gradients on the lower boundary.  Default = .false.
+
+**couple_dchidr_a_top**  
+  Logical flag indicating whether radial gradient of active scalar i should be coupled to other scalar fields or their gradients on the upper boundary.  Default = .false.
+**couple_dchidr_a_bottom**  
+  Logical flag indicating whether radial gradient of active scalar i should be coupled to other scalar fields or their gradients on the lower boundary.  Default = .false.
+
+**T_top**
+  Set the thermal variable, :math:`b_{\Theta,\Theta}`, at the top of the domain (overloaded)
+**T_top_file**
+  Set a spatially varying thermal variable, :math:`b_{\Theta,\Theta}`, at the top of the domain by specifying a generic input filename (overloaded, untested)
+**T_dTdr_coeff_top**
+  Set the coupling coefficient between the thermal variable and the radial derivative of the thermal variable, :math:`b_{\Theta,\frac{\partial \Theta}{\partial r}}`, at the top of the domain
+**T_chi_a_coeff_top(i)**
+  Set the coupling coefficient between the thermal variable and active scalar field i, :math:`b_{\Theta,\chi_{a_i}}`, at the top of the domain
+**T_dchidr_a_coeff_top(i)**
+  Set the coupling coefficient between the thermal variable and the radial derivative of active scalar field i, :math:`b_{\Theta,\frac{\partial \chi_{a_i}}{\partial r}}`, at the top of the domain
+
+**T_bottom**
+  Set the thermal variable, :math:`b_{\Theta,\Theta}`, at the base of the domain (overloaded)
+**T_bottom_file**
+  Set a spatially varying thermal variable, :math:`b_{\Theta,\Theta}`, at the base of the domain by specifying a generic input filename (overloaded, untested)
+**T_dTdr_coeff_bottom**
+  Set the coupling coefficient between the thermal variable and the radial derivative of the thermal variable, :math:`b_{\Theta,\frac{\partial \Theta}{\partial r}}`, at the base of the domain
+**T_chi_a_coeff_bottom(i)**
+  Set the coupling coefficient between the thermal variable and active scalar field i, :math:`b_{\Theta,\chi_{a_i}}`, at the base of the domain
+**T_dchidr_a_coeff_bottom(i)**
+  Set the coupling coefficient between the thermal variable and the radial derivative of active scalar field i, :math:`b_{\Theta,\frac{\partial \chi_{a_i}}{\partial r}}`, at the base of the domain
+
+**dTdr_top**
+  Set the radial derivative of the thermal variable, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial\Theta}{\partial r}}`, at the top of the domain (overloaded)
+**dTdr_top_file**
+  Set a spatially varying radial derivative of the thermal variable, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial\Theta}{\partial r}}`, at the top of the domain by specifying a generic input filename (overloaded, untested)
+**dTdr_T_coeff_top**
+  Set the coupling coefficient between the radial derivative of the thermal variable and the thermal variable, :math:`b_{\frac{\partial\Theta}{\partial r},\Theta}`, at the top of the domain
+**dTdr_chi_a_coeff_top(i)**
+  Set the coupling coefficient between the radial derivative of the thermal variable and the radial derivative of active scalar field i, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial \chi_{a_i}}{\partial r}}`, at the top of the domain
+**dTdr_dchidr_a_coeff_top(i)**
+  Set the coupling coefficient between the radial derivative of the thermal variable and the radial derivative of active scalar field i, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial \chi_{a_i}}{\partial r}}`, at the top of the domain
+
+**dTdr_bottom**
+  Set the radial derivative of the thermal variable, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial\Theta}{\partial r}}`, at the base of the domain (overloaded)
+**dTdr_bottom_file**
+  Set a spatially varying radial derivative of the thermal variable, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial\Theta}{\partial r}}`, at the base of the domain by specifying a generic input filename (overloaded, untested)
+**dTdr_T_coeff_bottom**
+  Set the coupling coefficient between the radial derivative of the thermal variable and the thermal variable, :math:`b_{\frac{\partial\Theta}{\partial r},\Theta}`, at the base of the domain
+**dTdr_chi_a_coeff_bottom(i)**
+  Set the coupling coefficient between the radial derivative of the thermal variable and the radial derivative of active scalar field i, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial \chi_{a_i}}{\partial r}}`, at the base of the domain
+**dTdr_dchidr_a_coeff_bottom(i)**
+  Set the coupling coefficient between the radial derivative of the thermal variable and the radial derivative of active scalar field i, :math:`b_{\frac{\partial\Theta}{\partial r},\frac{\partial \chi_{a_i}}{\partial r}}`, at the base of the domain
+
+
+**chi_a_top(i)**
+  Set active scalar field i, :math:`b_{\chi_{a_i},\chi_{a_i}}`, at the top of the domain (overloaded)
+**chi_a_top_file(i)**
+  Set a spatially varying active scalar field i, :math:`b_{\chi_{a_i},\chi_{a_i}}`, at the top of the domain by specifying a generic input filename (overloaded, untested)
+**chi_a_T_coeff_top(i)**
+  Set the coupling coefficient between active scalar field i and the thermal variable, :math:`b_{\chi_{a_i},\Theta}`, at the top of the domain
+**chi_a_dTdr_coeff_top(i)**
+  Set the coupling coefficient between active scalar field i and the radial derivative of the thermal variable, :math:`b_{\chi_{a_i},\frac{\partial\Theta}{\partial r}}`, at the top of the domain
+**chi_a_chi_a_coeff_top(i,j)**
+  Set the coupling coefficient between active scalar field i and active scalar field j, :math:`b_{\chi_{a_i},\chi_{a_j}}`, at the top of the domain.  :math:`b_{\chi_{a_i},\chi_{a_i}}` is ignored 
+**chi_a_dchidr_a_coeff_top(i,j)**
+  Set the coupling coefficient between active scalar field i and the radial derivative of active scalar field j, :math:`b_{\chi_{a_i},\frac{\partial \chi_{a_j}}{\partial r}}`, at the top of the domain
+
+**chi_a_bottom(i)**
+  Set active scalar field i, :math:`b_{\chi_{a_i},\chi_{a_i}}`, at the base of the domain (overloaded)
+**chi_a_bottom_file(i)**
+  Set a spatially varying active scalar field i, :math:`b_{\chi_{a_i},\chi_{a_i}}`, at the base of the domain by specifying a generic input filename (overloaded, untested)
+**chi_a_T_coeff_bottom(i)**
+  Set the coupling coefficient between active scalar field i and the thermal variable, :math:`b_{\chi_{a_i},\Theta}`, at the base of the domain
+**chi_a_dTdr_coeff_bottom(i)**
+  Set the coupling coefficient between active scalar field i and the radial derivative of the thermal variable, :math:`b_{\chi_{a_i},\frac{\partial\Theta}{\partial r}}`, at the base of the domain
+**chi_a_chi_a_coeff_bottom(i,j)**
+  Set the coupling coefficient between active scalar field i and active scalar field j, :math:`b_{\chi_{a_i},\chi_{a_j}}`, at the base of the domain.  :math:`b_{\chi_{a_i},\chi_{a_i}}` is ignored 
+**chi_a_dchidr_a_coeff_bottom(i,j)**
+  Set the coupling coefficient between active scalar field i and the radial derivative of active scalar field j, :math:`b_{\chi_{a_i},\frac{\partial \chi_{a_j}}{\partial r}}`, at the base of the domain
+
+**dchidr_a_top(i)**
+  Set the radial derivative of active scalar field i, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\frac{\partial \chi_{a_i}}{\partial r}}`, at the top of the domain (overloaded)
+**dchidr_a_top_file(i)**
+  Set a spatially varying radial derivative of active scalar field i, :math:`b_{\frac{\partial\chi_{a_i}}{\partial r},\frac{\partial\chi_{a_i}}{\partial r}}`, at the top of the domain by specifying a generic input filename (overloaded, untested)
+**dchidr_a_T_coeff_top(i)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and the thermal variable, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\Theta}`, at the top of the domain
+**dchidr_a_dTdr_coeff_top(i)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and the radial derivative of the thermal variable, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\frac{\partial\Theta}{\partial r}}`, at the top of the domain
+**dchidr_a_chi_a_coeff_top(i,j)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and active scalar field j, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\chi_{a_j}}`, at the top of the domain
+**dchidr_a_dchidr_a_coeff_top(i,j)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and the radial derivative of active scalar field j, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\frac{\partial \chi_{a_j}}{\partial r}}`, at the top of the domain.  :math:`b_{\frac{\partial\chi_{a_i}}{\partial r},\frac{\partial\chi_{a_i}}{\partial r}}` is ignored
+
+**dchidr_a_bottom(i)**
+  Set the radial derivative of active scalar field i, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\frac{\partial \chi_{a_i}}{\partial r}}`, at the base of the domain (overloaded)
+**dchidr_a_bottom_file(i)**
+  Set a spatially varying radial derivative of active scalar field i, :math:`b_{\frac{\partial\chi_{a_i}}{\partial r},\frac{\partial\chi_{a_i}}{\partial r}}`, at the base of the domain by specifying a generic input filename (overloaded, untested)
+**dchidr_a_T_coeff_bottom(i)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and the thermal variable, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\Theta}`, at the base of the domain
+**dchidr_a_dTdr_coeff_bottom(i)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and the radial derivative of the thermal variable, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\frac{\partial\Theta}{\partial r}}`, at the base of the domain
+**dchidr_a_chi_a_coeff_bottom(i,j)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and active scalar field j, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\chi_{a_j}}`, at the base of the domain
+**dchidr_a_dchidr_a_coeff_bottom(i,j)**
+  Set the coupling coefficient between the radial derivative of active scalar field i and the radial derivative of active scalar field j, :math:`b_{\frac{\partial \chi_{a_i}}{\partial r},\frac{\partial \chi_{a_j}}{\partial r}}`, at the base of the domain.  :math:`b_{\frac{\partial\chi_{a_i}}{\partial r},\frac{\partial\chi_{a_i}}{\partial r}}` is ignored
+
+Further Information
+^^^^^^^^^^^^^^^^^^^
+
+See `tests/coupled_bcs` for example input files.
+
+
+

doc/source/User_Guide/under_development.rst

@@ -17,6 +17,14 @@ Arbitrary Scalar Fields
 .. include:: arbitrary_scalar_fields.txt 
 
 
+.. _coupled_bcs:
+
+Coupled Boundary Conditions
+---------------------------
+
+.. include:: coupled_bcs.txt 
+
+
 
 
 

src/IO/Spherical_IO.F90

@@ -663,12 +663,12 @@ Subroutine Write_Full_3D(qty)
         Implicit None        
         Real*8, Intent(In) :: qty(:,my_rmin:,my_theta_min:)
         Integer :: i, funit
-        Character*4 :: qstring
+        Character*5 :: qstring
         Character*120 :: iterstring, data_file, grid_file
 
         ! Write the data file (Parallel I/O)
         Write(iterstring,i_ofmt) current_iteration
-        Write(qstring,'(i4.4)') current_qval
+        Write(qstring,'(i5.5)') current_qval
         data_file = trim(local_file_path)//'Spherical_3D/'//trim(iterstring)//'_'//qstring
         Call full_3d_buffer%cache_data(qty)
         Call full_3d_buffer%write_data(filename=data_file)