[cig-commits] r8113 - doc/CitcomS/manual

[tan2 at geodynamics.org]

Author: tan2
Date: 2007-10-15 18:19:58 -0700 (Mon, 15 Oct 2007)
New Revision: 8113

Modified:
   doc/CitcomS/manual/citcoms.lyx
Log:
Cookbook 9, unfinished

Modified: doc/CitcomS/manual/citcoms.lyx
===================================================================
--- doc/CitcomS/manual/citcoms.lyx	2007-10-16 00:38:15 UTC (rev 8112)
+++ doc/CitcomS/manual/citcoms.lyx	2007-10-16 01:19:58 UTC (rev 8113)
@@ -10182,10 +10182,10 @@
 \end_layout
 
 \begin_layout Standard
-Finaly, the rigid rotation component of the velocity solution is removed.
+Finally, the rigid body rotation component of the velocity solution is removed.
  The mode of rigid body rotation is unconstrainted by the Stokes equation,
  if free-slip boundary conditions are used for the top and bottom boundaries
- of a full spherical model.
+ in a full spherical model.
  However, for models with imposed plate velocity, it is advised to turn
  off 
 \family typewriter
@@ -10497,18 +10497,758 @@
 Problem
 \end_layout
 
+\begin_layout Standard
+You would like to model the interaction between a segment of mid-ocean ridge
+ and a plume.
+ A small grid spacing is required to resolve the thin plume conduit and
+ the flow near the ridge.
+ On the other hand, the plume must be sufficiently away from the sidewalls
+ to avoid possible boundary effects.
+ Satisfying both requirements in a model will take a long computation time.
+ Using solver coupling, a high-sesolution model with a smaller domain can
+ be nested within a low-resolution model, and the computation time is significan
+tly reduced.
+ 
+\end_layout
+
 \begin_layout Subsection
 Solution
 \end_layout
 
+\begin_layout Standard
+You will use two solvers in the model.
+ A special command line option is required for a coupled model.
+ Typing the following command to run this cookbook example:
+\end_layout
+
+\begin_layout LyX-Code
+$ citcoms --coupled cookbook9.cfg
+\end_layout
+
+\begin_layout Standard
+The embeded solver (esolver) is nested within the domain of the containing
+ solver (csolver).
+ Both solvers are instances of a regional CitcomS solver.
+ The containing solver can be a full CitcomS solver.
+\end_layout
+
+\begin_layout LyX-Code
+csolver = regional      ;containing solver
+\newline
+esolver = regional      ;embedded
+ solver
+\end_layout
+
+\begin_layout Standard
+You will use four processors for this model.
+ Each solver will use two processors.
+ The rank-0 and rank-1 processors will be assigned to the csolver, and rank-2
+ and rank-3 processors will be assigned to the esolver.
+\end_layout
+
+\begin_layout LyX-Code
+[CitcomS.layout]
+\newline
+# assigning processors to csolver and esolver
+\newline
+containing_group
+ = [0-1]
+\newline
+embedded_group = [2-3]
+\end_layout
+
+\begin_layout Standard
+The procedure for the nested solver coupling is described elsewhere 
+\begin_inset LatexCommand cite
+key "Tan et al GeoFramework Part I"
+
+\end_inset
+
+ and is briefly described in the followings:
+\end_layout
+
+\begin_layout Enumerate
+The containing solver solves the velocity and computes its time step size
+ 
+\begin_inset Formula $dt_{c}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Enumerate
+The containing solver interpolates the velocity and temperature onto the
+ boundary of the embedded model.
+\end_layout
+
+\begin_layout Enumerate
+The embedded model solves the velocity and temperature, using the boundary
+ conditions from step 2, with a time step size 
+\begin_inset Formula $dt_{e}$
+\end_inset
+
+.
+ 
+\begin_inset Formula $dt_{e}$
+\end_inset
+
+ is always smaller than 
+\begin_inset Formula $dt_{c}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Enumerate
+Goto step 3 until the sum of 
+\begin_inset Formula $dt_{e}$
+\end_inset
+
+ equal to 
+\begin_inset Formula $dt_{c}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Enumerate
+Optionally (if 
+\family typewriter
+two_way_communication
+\family default
+ is 
+\family typewriter
+on
+\family default
+), the containing solver updates its temperature according to embedded solver's
+ temperature.
+\end_layout
+
+\begin_layout Enumerate
+The containing solver solves the temperature with a time step size 
+\begin_inset Formula $dt_{c}$
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Enumerate
+Goto step 1.
+\end_layout
+
+\begin_layout Standard
+The two solver processes are seperated and only communicate through the
+ couplers, which, in turn, use the exchanger package to pass messages.
+ The containging coupler and controller (ccoupler and ccontroller) are associate
+d with the csolver, and the embedded coupler and controller (ecoupler and
+ econtroller) with the esolver.
+ Each of the two solvers will track its own number of time steps.
+ The esolver is have a smaller time step size and, hence, a larger number
+ of time steps.
+ The model will finish when either of the solver reach the 200th time step.
+ The csolver will output for every 2 steps and the esolver for every 10
+ steps.
+\end_layout
+
+\begin_layout LyX-Code
+[CitcomS]
+\newline
+steps = 200
+\newline
+
+\newline
+[CitcomS.ccontroller]
+\newline
+monitoringFrequency = 2
+\newline
+
+\newline
+[CitcomS.econtroll
+er]
+\newline
+monitoringFrequency = 10
+\end_layout
+
+\begin_layout Standard
+A few parameters must be indentical for the ccoupler and ecoupler.
+ You will use two-way communication, which enable ecoupler to send temperature
+ information to the ccoupler.
+ Otherwise, the communication is one way, ccoupler to ecoupler, only, and
+ the csolver is not affected by the esolver.
+\end_layout
+
+\begin_layout LyX-Code
+two_way_communication = on
+\end_layout
+
+\begin_layout Standard
+There is an option to exchange initial temperature, which could ensure that
+ the initial temperature field of both solvers are consistent.
+ The initial temperature field will be read from velo files, which already
+ contain consistent temperture fields, and don't need to exchange again.
+ 
+\end_layout
+
+\begin_layout LyX-Code
+exchange_initial_temperature = off
+\end_layout
+
+\begin_layout Standard
+Two additional parameters are for the ecoupler only.
+ These parameters specify whether the top and bottom boundary of the esolver
+ will be imposed with the velocity and temperature from the csolver.
+ For models with prescribed top or bottom boundary conditions, you can turn
+ on these two parameters.
+\end_layout
+
+\begin_layout LyX-Code
+exclude_top = off
+\newline
+exclude_bottom = off
+\end_layout
+
+\begin_layout Standard
+The velocity boundadry conditions of esolver is fixed normal velocity and
+ shear stress, whose values are received from the esolver.
+ Without turning on 
+\family typewriter
+side_sbcs
+\family default
+, the model will fail to run.
+\end_layout
+
+\begin_layout LyX-Code
+[CitcomS.esolver.bc]
+\newline
+side_sbcs = on
+\end_layout
+
+\begin_layout Standard
+Plate motion is imposed on top of the esolver, which has a mid-ocean ridge
+ with a 5 cm/yer half spreading rate.
+ A transfrom fault cuts through the ridge.
+ Setting 
+\family typewriter
+start_age
+\family default
+ to 0, the plate motion is read from the file 
+\family typewriter
+velocity/bvel.dat0
+\family default
+ and will be constant in time.
+\end_layout
+
+\begin_layout LyX-Code
+[CitcomS.csolver.bc]
+\newline
+topvbc = 1
+\newline
+
+\newline
+[CitcomS.csolver.param]
+\newline
+file_vbcs = on
+\newline
+vel_bound_file
+ = velocity/bvel.dat
+\newline
+start_age = 0
+\end_layout
+
+\begin_layout Standard
+The domain of the csolver is bigger than that of the esolver.
+ The radial dimension of esolver is shrank slightly with repect to csolver
+ so that the domain of esolver is completely inside the domain of csolver.
+ The radial coordinate of csolver is refined near the top and bottom boundary
+ (
+\family typewriter
+coor=2
+\family default
+), with the lower 10% of the mesh divided by 15% of nodes, upper 10% of
+ the mesh divided by 20% of nodes, and the rest 80% of the mesh divided
+ by 75% of nodes.
+ Be cautious that if the mesh size changes too rapidly across a element,
+ the temperature solver might generate pronouncing numerical artifact.
+\end_layout
+
+\begin_layout LyX-Code
+[CitcomS.csolver.mesher]
+\newline
+nprocz = 2
+\newline
+nodex = 17
+\newline
+nodey = 17
+\newline
+nodez = 25
+\newline
+radius_outer
+ = 1.0
+\newline
+radius_inner = 0.55
+\newline
+theta_min = 1.171
+\newline
+theta_max = 1.971
+\newline
+fi_min = 0
+\newline
+fi_max
+ = 0.8
+\newline
+coor = 2
+\newline
+coor_refine = 0.1,0.15,0.1,0.2
+\newline
+
+\newline
+[CitcomS.esolver.mesher]
+\newline
+nprocz = 2
+\newline
+nodex
+ = 21
+\newline
+nodey = 21
+\newline
+nodez = 49
+\newline
+radius_outer = 0.999
+\newline
+radius_inner = 0.551
+\newline
+theta_min
+ = 1.421
+\newline
+theta_max = 1.721
+\newline
+fi_min = 0.25
+\newline
+fi_max = 0.55
+\end_layout
+
+\begin_layout Standard
+The temperature solver has several parameters to tune its behavior.
+ The temperature solver is turned on (
+\family typewriter
+ADV
+\family default
+).
+ A Lenardic-type filter, which removes numerical artifact while keeping
+ total energy conserved, is disabled (
+\family typewriter
+filter_temp
+\family default
+).
+ The maximum temperature can be monitor between time steps (
+\family typewriter
+monitor_max_T
+\family default
+).
+ If the maximum temperature increases too much (> 5%) between time steps,
+ the temperature solve will rerun with half time step size.
+ The time step size is usually determined dynamically according Courant
+ criterion and is reduced by a fraction (
+\family typewriter
+finetunedt
+\family default
+) to improve the accuracy.
+ The time step size can also be specified staticly in 
+\family typewriter
+fixed_timestep
+\family default
+, if 
+\family typewriter
+fixed_timestep
+\family default
+ is non-zero.
+ The temperature solver uses a explicitly predictor-corrector algorithm.
+ Using 0.5 for the predictor (
+\family typewriter
+adv_gamma
+\family default
+) and 2 iterations for the corrector (
+\family typewriter
+adv_sub_iterations
+\family default
+), this algorithm is 2nd order accurate.
+\end_layout
+
+\begin_layout LyX-Code
+ADV = on
+\newline
+filter_temp = off
+\newline
+monitor_max_T = off
+\newline
+finetunedt = 0.9
+\newline
+fixed_timestep
+ = 0
+\newline
+adv_gamma = 0.5
+\newline
+adv_sub_iterations = 2
+\end_layout
+
 \begin_layout Subsubsection
 Example: Nested Solver Coupling for Ridge-Plume Interaction, cookbook9.cfg
 \end_layout
 
+\begin_layout LyX-Code
+# Cookbook 9: Nested Solver Coupling for Ridge-Plume Interation
+\newline
+
+\newline
+[CitcomS]
+\newline
+steps
+ = 200
+\newline
+
+\newline
+csolver = regional      ;containing solver
+\newline
+esolver = regional     
+ ;embedded solver
+\newline
+
+\newline
+
+\newline
+[CitcomS.ccoupler]
+\newline
+two_way_communication = on
+\newline
+exchange_initial_tem
+perature = off
+\newline
+
+\newline
+
+\newline
+[CitcomS.ecoupler]
+\newline
+two_way_communication = on
+\newline
+exchange_initial_temper
+ature = off
+\newline
+exclude_top = off
+\newline
+exclude_bottom = off
+\newline
+
+\newline
+
+\newline
+[CitcomS.layout]
+\newline
+# assigning
+ processors to csolver and esolver
+\newline
+containing_group = [0-1]
+\newline
+embedded_group
+ = [2-3]
+\newline
+
+\newline
+
+\newline
+[CitcomS.ccontroller]
+\newline
+monitoringFrequency = 2
+\newline
+
+\newline
+
+\newline
+[CitcomS.econtroller]
+\newline
+monitorin
+gFrequency = 10
+\newline
+
+\newline
+
+\newline
+[CitcomS.csolver]
+\newline
+datadir_old = ic
+\newline
+datafile_old = cntn
+\newline
+datadir
+ = output
+\newline
+datafile = cntn
+\newline
+rayleigh = 1e8
+\newline
+
+\newline
+
+\newline
+[CitcomS.csolver.mesher]
+\newline
+nprocz = 2
+\newline
+nodex
+ = 17
+\newline
+nodey = 17
+\newline
+nodez = 25
+\newline
+radius_outer = 1.0
+\newline
+radius_inner = 0.55
+\newline
+theta_min =
+ 1.171
+\newline
+theta_max = 1.971
+\newline
+fi_min = 0
+\newline
+fi_max = 0.8
+\newline
+coor = 2
+\newline
+coor_refine = 0.1,0.15,0.1,0.2
+\newline
+
+\newline
+
+\newline
+[Cit
+comS.csolver.bc]
+\newline
+topvbc = 1
+\newline
+
+\newline
+
+\newline
+[CitcomS.csolver.param]
+\newline
+file_vbcs = on
+\newline
+vel_bound_file
+ = velocity/bvel.dat
+\newline
+start_age = 0
+\newline
+
+\newline
+
+\newline
+[CitcomS.csolver.ic]
+\newline
+tic_method = -1
+\newline
+solution_cycles
+_init = 0
+\newline
+
+\newline
+
+\newline
+[CitcomS.csolver.tsolver]
+\newline
+ADV = on
+\newline
+filter_temp = off
+\newline
+monitor_max_T =
+ off
+\newline
+finetunedt = 0.9
+\newline
+fixed_timestep = 0
+\newline
+adv_gamma = 0.5
+\newline
+adv_sub_iterations =
+ 2
+\newline
+
+\newline
+
+\newline
+[CitcomS.csolver.vsolver]
+\newline
+tole_compressibility = 8e-6
+\newline
+
+\newline
+
+\newline
+[CitcomS.csolver.visc]
+\newline
+VISC_UPD
+ATE = on
+\newline
+num_mat = 4
+\newline
+visc0 = 1,1,1,1
+\newline
+TDEPV = on
+\newline
+viscE = 1.6,1.6,1.6,1.6
+\newline
+viscT = 0,0,0,0
+\newline
+VM
+IN = on
+\newline
+visc_min = 1.0
+\newline
+VMAX = on
+\newline
+visc_max = 100.0
+\newline
+
+\newline
+
+\newline
+####################################
+###########
+\newline
+
+\newline
+[CitcomS.esolver]
+\newline
+datadir_old = ic
+\newline
+datafile_old = embd
+\newline
+datadir =
+ output
+\newline
+datafile = embd
+\newline
+rayleigh = 1e8
+\newline
+
+\newline
+
+\newline
+[CitcomS.esolver.mesher]
+\newline
+nprocz = 2
+\newline
+nodex
+ = 21
+\newline
+nodey = 21
+\newline
+nodez = 49
+\newline
+radius_outer = 0.999
+\newline
+radius_inner = 0.551
+\newline
+theta_min
+ = 1.421
+\newline
+theta_max = 1.721
+\newline
+fi_min = 0.25
+\newline
+fi_max = 0.55
+\newline
+
+\newline
+
+\newline
+[CitcomS.esolver.ic]
+\newline
+tic_method
+ = -1
+\newline
+solution_cycles_init = 0
+\newline
+
+\newline
+
+\newline
+[CitcomS.esolver.vsolver]
+\newline
+tole_compressibility
+ = 6e-6
+\newline
+
+\newline
+
+\newline
+[CitcomS.esolver.tsolver]
+\newline
+ADV = on
+\newline
+filter_temp = off
+\newline
+monitor_max_T = off
+\newline
+finetu
+nedt = 0.9
+\newline
+fixed_timestep = 0
+\newline
+adv_gamma = 0.5
+\newline
+adv_sub_iterations = 2
+\newline
+
+\newline
+
+\newline
+[CitcomS.esolver.vi
+sc]
+\newline
+VISC_UPDATE = on
+\newline
+num_mat = 4
+\newline
+visc0 = 1,1,1,1
+\newline
+TDEPV = on
+\newline
+viscE = 1.6,1.6,1.6,1.6
+\newline
+viscT
+ = 0,0,0,0
+\newline
+VMIN = on
+\newline
+visc_min = 1.0
+\newline
+VMAX = on
+\newline
+visc_max = 100.0
+\newline
+
+\newline
+
+\newline
+[CitcomS.esolver.bc]
+\newline
+side_s
+bcs = on
+\end_layout
+
 \begin_layout Subsection
 Discussion
 \end_layout
 
+\begin_layout Standard
+(TODO) The final step.
+ The isosurface is at 0.8.
+ The resolution of both meshes is reduced approximately three-folds for
+ better visualization.
+\end_layout
+
 \begin_layout Part
 Appendices
 \end_layout