couette.xml

This section explains the XML-tags and values in the couette.xml configuration file.

Execute ./mamico-cfg in the tools folder in order to create a couette.xml file with some basic settings.
(Deprecated: Some template configurations are also provided in the examples folder.)

In the following (sub)sections, the keys to the corresponding XML tags under <scenario-configuration> are explained.
Keys which can be set using config-generator/run are marked with ^†.

couette-test

domain

Key	Example Value	Description
channelheight†	50	The distance along the z-axis of the two parallel walls enclosing the domain. The domain is defined as being cubic, thus also the total domain size is dictated by this value.
wall-init-velocity	0.0 ; 0.0 ; 0.0	The initial velocity of the wall, stored in a 3-dimensional double-valued vector. Note that it will only be used when wall-init-cycles is unequal to zero.
wall-init-cycles	0	The number of coupling cycles in which the velocity defined in wall-init-velocity instead of wall-velocity is to be used. The transition from wall-init-velocity to wall-velocity will not be interpolated. There is no interpolation between wall-init-velocity and wall-velocity.
wall-velocity	0.5 ; 0.0 ; 0.0	The velocity of the wall, stored in a 3-dimensional double-valued vector.
wall-oscilations	0	Can be used to set an oscilating velocity of the wall which is defined by the following formula wall-velocity * cos(2PI * wall-oscillations * CYCLE / coupling-cycles). Thus the value wall-oscilations sets the number of periods that are run over during the simulation.

coupling

Key	Example Value	Description
coupling-cycles	50	The total number of coupling cycles to run during the simulation, where each cycle comprises the defined number of MD time steps. Sensible values range from ~200-5000
two-way-couping†	no	If enabled (yes), MD data is used as boundary conditions for macro solver. Best leave set to no.
send-from-md-to-macro	yes	If enabled MD data is transferred, merging and communications to macroscopic solver ranks is allowed. This will NOT let MD results influence the marco-scale solver but it used for the generation of .csv-files.
send-from-macro-to-md	yes	Enables data extraction from couette solver and communication to MD ranks. Recommended to be set to yes.
filter-init-cycles	0	Number of cycles with two-way-coupling and compute-snr disabled at simulation startup, used for initialisation of noise filter.
write-csv-every-timestep	10	Determines interval (coupling cycles) in which MD-data is written to generated .csv-files for evaluation after the simulation. Use 0 to disable this feature.
compute-snr	no	If enabled (yes), the computed signal-to-noise ratio between filter output and the macroscopic solver is written to stdout. Only use this feature for sequential test!

macroscopic-solver

Key	Example Value	Description
type†	lb	Supports lb (Lattice Boltzmann (LB) solver), fd (simple, sequential finite difference solver), foam (sequential, finite difference solver icoFoam from OpenFOAM) or analytical. Note that analytic solver only supports flow in x-direction, is only active on rank 0, and that it does not model viscous shear forces in the oscillating wall case (i.e. changes of wall-velocity are propagated through the whole domain instantaneously). The LB solver does not impose these limitations and can be parallelized.
viscosity	2.14	Dynamic viscosity of the fluid.
number-of-processes	1 ; 1 ; 1	Only for the LB solver: Number of LB ranks per direction (x; y; z).
plot-every-timestep	2	Only for the LB solver: Determines interval (coupling cycles) in which to plot the data (VTK).
init-advance-cycles	0	Advances the macroscopic-solver before starting the coupling. Can be used for analytic solver and oscillating wall, to skip couette startup.
foam-setup-directory	/absolute/path/to/OpenFOAM/setup	Path to the OpenFOAM setup directory.
foam-setup-folder	FoamSetup	Name of the OpenFOAM folder.
boundaries-with-MD	0; 0; 0; 0; 0; 0; 1; 1; 1; 1; 1; 1	Only for the OpenFOAM solver: Vector of twelve 0s and 1s, with 1 for a boundary of OpenFOAM coupled with MaMiCo (uses the order according to the blockMesh order) and 0 when the boundary shall not be coupled.

microscopic-solver

Key	Example Value	Description
type†	md	Supports md (SimpleMD), synthetic (data from macroscopic plus gaussian noise) or ls1 (ls1-MarDyn). Synthetic runs sequentially only and does not support parallel communication, so send-from-md-to-macro and send-from-macro-to-md in coupling must be no. Hence, in the Synthetic + LB case, number-of-processes in macroscopic-solver must be 1 ; 1 ; 1.
temperature	1.1	Temperature of MD system, is initially applied to the molecules using the thermostat. (Not used by synthetic MD)
equilibrium-steps(†)	10000	Number of MD timesteps to run before start of coupled simulation. Can be 0 if MD checkpoint is used. (Not used by synthetic MD)
number-of-simulations†	4	Total number of MD instances. Set to 1 to disable multi-instance sampling. Set to dynamic to change the ensemble size at runtime as required. Must be 1 if type is synthetic. (Synthetic MD does not support multi-instance sampling.)
min-number-md	1	Required for dynamic number of simulations: Minimum number of MD instances.
error-start	0.1	Required for dynamic number of simulations: Error threshold at the start of the simulation.
error-end	0.05	Required for dynamic number of simulations: Error threshold at the end of the simulation.
density	0.813037037	Density of the fluid. Should be equal to molecules-per-direction[0] / domain-size[0] * molecules-per-direction[1] / domain-size[1] * molecules-per-direction[2] / domain-size[2], unless MD checkpoint is used.
double noise-sigma	0.1667	Only for the synthetic solver: Standard deviation of gaussian noise used to emulate MD flow field data.

tws-loop

Optional tag for running the couette test multiple times using different time-window-sizes (tws).
TODO: Explain this better.

Key	Example Value	Description
min	3	Starting value of tws.
max	100	Stopping value of tws.
step	5	Increments tws by step. (Defaults to 1 if not present)

mamico

macroscopic-cell-configuration

Key	Example Value	Description
cell-size†	2.5 ; 2.5 ; 2.5	Coupling cell size.
linked-cells-per-macroscopic-cell	1 ; 1 ; 1	Number of MD cells per MaMiCo coupling cell.
write-every-microscopic-timestep	0	VTK plotting frequency for the MD solver in coupling cycles.
microscopic-filename	CouplingCell_micro	VTK plotting file for the MD solver data.
write-every-macroscopic-timestep	0	VTK plotting frequency for the macroscopic solver in coupling cycles.
macroscopic-filename	CouplingCell_macro	VTK plotting file for the macroscopic solver data.

particle-insertion

The particle insertion method is linked to the boundary condition.^(†)

Key	Example Value	Description
type	usher	Use usher for reflecting boundaries (s. domain-configuration for Simple MD) and none for periodic ones.
maximum-number-of-iterations	100	TODO
maximum-number-of-restarts	500	TODO
insert-every-timestep	10	TODO
tolerance	0.5	TODO

momentum-insertion

Key	Example Value	Description
type	nie-velocity-imposition	TODO
outermost-overlap-layer	2	TODO
innermost-overlap-layer	3	TODO

tranfer-strategy

Key	Example Value	Description
type	nie-transfer	TODO
mass-flux-west	yes	TODO
mass-flux-east	yes	TODO
mass-flux-north	no	TODO
mass-flux-south	no	TODO
mass-flux-bottom	no	TODO
mass-flux-top	no	TODO
shift-by-timesteps	0.5	TODO

boundary-force

The boundary force is linked to the boundary condition.^(†)

Key	Example Value	Description
type	zhou-boundary-force	Use zhou-boundary-force for reflecting boundaries (s. domain-configuration for Simple MD) and none for periodic ones with yes and no respectively for all directions below.
west	yes	TODO
east	yes	TODO
north	yes	TODO
south	yes	TODO
bottom	yes	TODO
top	yes	TODO
density	0.81	TODO
temperature	1.1	TODO

parallel-topology

Key	Example Value	Description
type	xyz	Use xyz with Simple MD and zyx for ls1.

thermostat

The thermostat option defines, where to apply the temperature defined in macroscopic-solver within the MD region.

Key	Example Value	Description
type	outerLayers	The following values are available: all applies the thermostat in every cell of the MD region, outerLayers applies the thermostat the value defined in number-layers, starting with the most outer layer, onlyOutestLayer applies the thermostat only in the outest cell layer of the MD region, nowhere applies the thermostat nowehere within the MD region.
number-layers	1	Number of couplings cells on every border affected by the thermostate if the type is outerLayers.

molecular-dynamics

Configuration specific to the Simple MD solver and only relevant if md type is used in microscopic-solver.

molecule-configuration

Key	Example Value	Description
mass	1.0	Mass of the individual Lennard-Jones (LJ) particles.
temperature	1.27	Temperature of the simulation.
sigma	1.0	Distance at which the force between two LJ particles is zero.
epsilon	1.0	Maximum of the attractive energy between two LJ particles.
mean-velocity	0.0 ; 0.0 ; 0.0	TODO

mpi-configuration

Key	Example Value	Description
number-of-processes†	1 ; 1 ; 1	The number of MPI ranks must be divisible over the processes across all dimensions and the number of linked cells must be divisible by the number-of-processes.

simulation-configuration

Key	Example Value	Description
dt	0.005	Time step size within the molecular dynamics solver. Best leave to the standard value of 0.005 to avoid instability.
number-of-timesteps	50	Number of timesteps between coupling cylces.
reorganise-memory-every-timesteps	20	TODO
cumpute-macroscopic-quantities-every-timestep	0	TODO
fix-seed	no	If enabled (yes) simulation runs are reproducible.

vtk-configuration

Key	Example Value	Description
filename	Molecules	VTK molecules filename.
write-every-timestep	0	Frequency for writing VTK files in MD simulation time steps.

adios2-configuration

Key	Example Value	Description
directory-name	adiosOutput	TODO
write-every-timestep	0	Output interval in MD simulation time steps.

checkpoint-configuration

Key	Example Value	Description
filename	CheckpointSimpleMD	Filename prefix for Simple MD checkpoints
write-every-timestep	0	Checkpoint interval in MD simulation time steps.

domain-configuration

Only used by Simple MD in microscopic-solver.

Key	Example Value	Description
init-from-sequential-checkpoint†	CheckpointSimpleMD_10000_reflecting	Checkpoint filename (without extension) from which to initialize the Simple MD simulation.
init-from-checkpoint	CheckpointSimpleMD_10000_reflecting	Checkpoint filename (without extension and rank) from which to initialize the Simple MD simulation where every rank reads its corresponding checkpoint file. Used instead of init-from-sequential-checkpoint if the checkpoint is split into multiple files (Generated using multiple ranks).
molecules-per-direction	28 ; 28 ; 28	Number of molecules in the domain along each axis.
domain-size†	30.0 ; 30.0 ; 30.0	MD domain size along each axis.
domain-offset	10.0 ; 10.0 ; 2.5	Position of the MD domain in the macroscopic domain.
cutoff-radius	2.2	Lenard-Jones cut-off radius for force pair calculations.
linked-cell-size	2.5 ; 2.5 ; 2.5	Linked cell size.
k_B	1.0	Boltzmann constant
block-size	100	TODO
Multiple directions (Vertical directions top or bottom or the eight compas directions, such as north-east or a combination of both such as top-west)†	reflecting	Either reflecting or periodic boundary condition.

filter-pipeline

per-instance

Key	Example Value	Description
output†	md	The (optional) filter pipeline must define an output filter. If no filter should be applied, use md.

post-multi-instance

Key	Example Value	Description
output	md	The (optional) filter pipeline must define an output filter. If no filter should be applied, use md.