General information

With the help of cmusen the command line calculations can be performed on Windows or Linux. Usage:

cmusen -key[=value] [-key[=value] [...]]

Key	Description	Example
-s, -script	Path to script file	cmusen -script=/home/script.txt
-t, -threads	Maximum number of threads available for the program	cmusen -threads=8
-a, -affinity	Hexadecimal mask of cores pin threads to them	cmusen -affinity=7F
-v, -version	Print information about current version	cmusen -version
-m, -models	Print information about available models and their parameters	cmusen -models

Call cmusen without parameters to show help with all the available options listed here.

Note: On Linux, there is a difference between lowercase and uppercase letters.

Script file

The running script file is a text file. Each new row of this file defines a specific parameter needed to perform calculations.

Main parameters

To start calculations, it is required to specify an input and an output file, as well as the computational component that will be used. Depending on the type of the component selected, different parameters can be defined in the script.

Identifier	Value	Comments
JOB		An optional parameter that allows defining several jobs in one script file. If there is only one job, this parameter can be skipped.
SOURCE_FILE	Path	The name of the file to be opened. Read/write access must be allowed for this file.
RESULT_FILE	Path	The output file to which the results will be saved.
COMPONENT	Component	The following components are available:• SIMULATOR• PACKAGE_GENERATOR• BONDS_GENERATOR• RESULTS_ANALYZER• SNAPSHOT_GENERATOR• EXPORT_TO_TEXT• IMPORT_FROM_TEXT

DEM simulation – SIMULATOR component

The source file to be opened already contains a set of parameters needed to perform the simulation.
However, it is possible to override these settings using the options listed below.

Identifier	Value	Comments
SIMULATION_STEP	Time step [s]	Simulation time step.
SAVING_STEP	Time step [s]	Saving time step.
END_TIME	Time [s]	End simulation time.
SIMULATION_STEP_FACTOR	Factor	Sets simulation time step as a factor relative to the recommended time step. If SIMULATION_STEP is also defined, overrides it.
SAVING_STEP_FACTOR	Factor	Sets saving time step as a factor relative to the recommended time step. If SAVING_STEP is also defined, overrides it.
END_TIME_FACTOR	Factor	Sets end simulation time as a factor relative to the recommended time step. If END_TIME is also defined, overrides it.
SIMULATOR_TYPE	CPU or GPU	CPU – default simulation using CPU. GPU – CUDA simulation using GPU.
MODEL_PP	ModelPPName	Contact model to describe particle–particle interactions.
MODEL_PW	ModelPWName	Contact model to describe particle–wall interactions.
MODEL_SB	ModelSBName	Model to describe solid bonds.
MODEL_LB	ModelLBName	Model to describe liquid bridges.
MODEL_EF	ModelEFName	Model to describe external forces.
MODEL_PPHT	ModelPPHTName	Model to describe particle–particle heat transfer.
MODEL_PP_PARAMS	Parameters	Parameters for the MODEL_PP model. Only considered if MODEL_PP is used.
MODEL_PW_PARAMS	Parameters	Parameters for the MODEL_PW model. Only considered if MODEL_PW is used.
MODEL_SB_PARAMS	Parameters	Parameters for the MODEL_SB model. Only considered if MODEL_SB is used.
MODEL_LB_PARAMS	Parameters	Parameters for the MODEL_LB model. Only considered if MODEL_LB is used.
MODEL_EF_PARAMS	Parameters	Parameters for the MODEL_EF model. Only considered if MODEL_EF is used.
MODEL_PPHT_PARAMS	Parameters	Parameters for the MODEL_PPHT model. Only considered if MODEL_PPHT is used.
EXT_ACCEL	X Y Z	External acceleration for three coordinates.
SIMULATION_DOMAIN	Xₘᵢₙ Yₘᵢₙ Zₘᵢₙ Xₘₐₓ Yₘₐₓ Zₘₐₓ	The simulation domain in which the modelling is performed.
PBC_FLAGS	YES/NO YES/NO YES/NO	Periodic boundary conditions enabled in X/Y/Z directions.
PBC_DOMAIN	Xₘᵢₙ Yₘᵢₙ Zₘᵢₙ Xₘₐₓ Yₘₐₓ Zₘₐₓ	The domain of periodic boundary conditions.
AGGLOMERATES_DB	Path	File path to agglomerates DB. Required only if agglomerates are generated during simulation.
CONNECTED_PP_CONTACT	YES/NO	NO – no contacts between particles directly connected with bonds. YES – treat contacts between bonded particles normally.
ANISOTROPY	YES/NO	NO – do not consider particle anisotropy. YES – consider particle anisotropy.
DIFF_CONTACT_RADIUS	YES/NO	NO – radius and contact radius are the same. YES – contact radius differs from particle radius.
RESET_INITIAL_BOND_LENGTH	YES/NO	If YES, sets initial bond length equal to current bond length at time 0 before simulation starts.
VERLET_AUTO	YES/NO	NO – no automatic adaptation of Verlet distance. YES – enable automatic adaptation.
VERLET_COEF	Value	Verlet coefficient. If VERLET_AUTO is enabled, this is the initial value.
VERLET_MAX_CELLS	Number	Maximum number of cells used for the Verlet list.
VARIABLE_TIME_STEP	YES/NO	NO – constant time step. YES – variable simulation time step.
MAX_PART_MOVE	Distance [m]	Maximum allowed particle movement per time step. Used only if VARIABLE_TIME_STEP is enabled.
STEP_INC_FACTOR	Factor	Factor for increasing simulation time step. Used only if VARIABLE_TIME_STEP is enabled.
LIMIT_PARTICLE_VELOCITY	Velocity [m/s]	Maximum allowed particle velocity. Set to 0 to disable the limit.
SELECTIVE_SAVING_P	0/1 0/1 0/1 0/1 0/1 0/1 0/1	Defines which particle properties are saved.
SELECTIVE_SAVING_TW	0/1 0/1 0/1	Defines which wall properties are saved.
SELECTIVE_SAVING_SB	0/1 0/1 0/1	Defines which solid bond properties are saved.
SELECTIVE_SAVING_LB	0/1	Defines whether liquid bridge properties are saved.
MATERIAL_PROPERTY	Property CompoundKey Value	Supported properties: DENSITY, HEAT_CAPACITY, DYNAMIC_VISCOSITY, THERMAL_CONDUCTIVITY, YOUNG_MODULUS, NORMAL_STRENGTH, TANGENTIAL_STRENGTH, POISSON_RATIO, SURFACE_ENERGY, ATOMIC_VOLUME, SURFACE_TENSION, TIME_THERM_EXP_COEFF, YIELD_STRENGTH
INTERACTION_PROPERTY	Property CompoundKey1 CompoundKey2 Value	Supported properties: RESTITUTION_COEFFICIENT, SLIDING_FRICTION, ROLLING_FRICTION

Selective Saving

The input parameter for each SELECTIVE_SAVING_XXX identifier must be a binary sequence. Each symbol in the sequence indicates whether the corresponding property should be saved (1) or not (0).

Example: To save only forces and velocities of particles, add the following line to the script file:

SELECTIVE_SAVING_P 0 0 1 0 1 0

Model Parameters

Each model can have its own set of configurable parameters.

You can:

• View the list of available parameters in the Model Manager (graphical interface), or
• Use the -m option in the command-line version.

To set a specific parameter from the command line, use identifiers such as MODEL_PP_PARAMS, MODEL_PW_PARAMS, etc.
Each parameter must be specified as a pair: the parameter name and its corresponding value. If you need to change a parameter, you need to set all model parameters. The MODEL_XX_PARAMS is only considered if the corresponding MODEL_XX is used in the script.

Packing Generation – PACKAGE_GENERATOR Component

To generate particle packing, the PACKAGE_GENERATOR component can be used.
By default, all parameters defined in the source file (SOURCE_FILE) will be used.
To override some values, the following options can be applied:

Identifier	Value	Comments
PACK_GEN_VOLUME	GeneratorIndex Name/Key	Name or key of the virtual volume where to generate particles.
PACK_GEN_MIXTURE	GeneratorIndex Name/Key	Name or key of the mixture to generate.
PACK_GEN_POROSITY	GeneratorIndex Value	Target generation porosity.
PACK_GEN_OVERLAP	GeneratorIndex Value	Target maximum overlap between particles.
PACK_GEN_ITERATIONS	GeneratorIndex Value	Maximum allowed number of iterations.
PACK_GEN_VELOCITY	GeneratorIndex X Y Z	Initial velocity of generated particles.
PACK_GEN_INSIDE	GeneratorIndex YES/NO	Whether to generate particles inside real geometries.
SIMULATOR_TYPE	CPU or GPU	CPU – default simulation using CPU. GPU – CUDA simulation using GPU.
VERLET_COEF	Value	Verlet coefficient value.
MIXTURE_PROPERTY	MixtureIndex FractionIndex CompoundKey Diameter NumberFraction	Changes existing mixtures.

Export Scene – EXPORT_TO_TEXT Component

Identifier	Value	Comments
TIME_INTERVAL	TimeMin TimeMax	Exported time interval.
TEXT_EXPORT_PRECISION	Value	Double precision for values.
TEXT_EXPORT_OBJECTS	0/1 0/1 0/1	Selection of object types for export: Particles – Solid bonds – Walls.
TEXT_EXPORT_CONST	0/1 0/1 0/1 0/1 0/1	Selection of constant object properties for export: ID – Type – Geometry info – Material – Activity interval.
TEXT_EXPORT_TD_PART	0/1 0/1 0/1 0/1 0/1 0/1 0/1 0/1 0/1	Selection of time-dependent object properties of particles for export: Angular velocity – Coordinates – Force – Force amplitude – Orientation – Principal stress – Stress tensor – Temperature – Velocity.
TEXT_EXPORT_TD_BOND	0/1 0/1 0/1 0/1 0/1 0/1 0/1	Selection of time-dependent object properties of bonds for export: Coordinates – Force – Force amplitude – Tangential overlap – Temperature – Total torque – Velocity.
TEXT_EXPORT_TD_WALL	0/1 0/1 0/1 0/1	Selection of time-dependent object properties of walls for export: Coordinates – Force – Force amplitude – Velocity.
TEXT_EXPORT_SCENE	0/1 0/1 0/1 0/1	Selection of scene information for export: Simulation domain – Periodical boundary conditions – Anisotropy flag – Contact radius flag.
TEXT_EXPORT_GEOMETRIES	0/1 0/1 0/1 0/1	Selection of geometries information for export: Basic info – Time-dependent properties – Walls lists – Analysis volumes.
TEXT_EXPORT_MATERIALS	0/1 0/1 0/1	Selection of materials information for export: Compounds – Interactions – Mixtures.
TEXT_EXPORT_GENERATORS	0/1 0/1	Selection of generators for export: Package generator – Bonds generator.

Create Snapshot – SNAPSHOT_GENERATOR Component

The snapshot generator is used to save a specific time point as a separate file.

Identifier	Value	Comments
SNAPSHOT_TIME	Time point [s]	Time point for which a snapshot should be generated.

Results Analysis – RESULTS_ANALYZER Component

Identifier	Value	Comments
POSTPROCESS	GeometriesAnalyzer Variable,Variable,(…) Geometry [Filename]
POSTPROCESS	BondsAnalyzer Variable ResultType [Filename]
POSTPROCESS	ParticlesAnalyzer Variable ResultType [Filename]
POSTPROCESS	AgglomeratesAnalyzer Variable ResultType [Filename]

Exemplary Scripts

All exemplary scripts are located in the installation folder.

Basic Script

A minimal script that opens an existing file initial.mdem, performs the simulation, and writes the results into results.mdem. All parameters specified in initial.mdem are used for the simulation.

SOURCE_FILE     D:\My simulations\initial.mdem
RESULT_FILE     D:\My simulations\results.mdem
COMPONENT       SIMULATOR

Main Simulation Parameters

SOURCE_FILE           D:\My simulations\initial.mdem
RESULT_FILE           D:\My simulations\results.mdem
COMPONENT             SIMULATOR
SIMULATION_STEP       2e-8
SAVING_STEP           1e-5
END_TIME              1e-3
EXT_ACCEL             0 0 -9.81
SIMULATION_DOMAIN    -0.03 -0.03 -0.018 0.03 0.03 0.018

Model Selection and Parameter Specification

To use a built-in model, specify the model name. If you have your own model, specify the full path to it. To change model parameters, use MODEL_*_PARAMS and list all parameters with their values. To view all available models and their parameters, run:

cmusen.exe -m

SOURCE_FILE       D:\My simulations\initial.mdem
RESULT_FILE       D:\My simulations\results.mdem
COMPONENT         SIMULATOR
MODEL_PP          ModelPPHertzMindlin
MODEL_PW          ModelPWHertzMindlin
MODEL_SB          ModelSBElastic
MODEL_SB_PARAMS   CONSIDER_BREAKAGE 1 BIMODULARITY 1 COMPRESSIVE_BREAK 0

Packing Generation with Custom PSD

You can modify the particle size distribution (PSD) and number fractions of mixture components. In the example below, a generator with index 1 creates Mixture0 inside the GenerationDomain analysis volume. This mixture contains 4 particle fractions of different types and sizes. Note: The sum of number fractions must be equal to 1.

SOURCE_FILE          D:\My simulations\initial.mdem
RESULT_FILE          D:\My simulations\results.mdem
COMPONENT            PACKAGE_GENERATOR
PACK_GEN_VOLUME      1 GenerationDomain
PACK_GEN_MIXTURE     1 Mixture0
PACK_GEN_POROSITY    1 0.5
PACK_GEN_OVERLAP     1 1e-7
PACK_GEN_ITERATIONS  1 1e+5
PACK_GEN_VELOCITY    1 0 0 -0.1
PACK_GEN_INSIDE      1 NO
SIMULATOR_TYPE       CPU
VERLET_COEF          2
MIXTURE_PROPERTY     1 1 CG9ZE5YQBM 1.5e-3 0.4
MIXTURE_PROPERTY     1 2 CG9ZE5YQBM 1.8e-3 0.3
MIXTURE_PROPERTY     1 3 BWLPWOW76F 1.9e-3 0.2
MIXTURE_PROPERTY     1 4 BWLPWOW76F 2.1e-3 0.1

Multiple Jobs in One Script

You can define multiple tasks in a single script file. They will be executed sequentially, in the order they appear. The example below first generates a packing, then simulates the generated scene.

JOB
SOURCE_FILE ../InitScenes/PackingGeneration.mdem
RESULT_FILE ./Result_PackingGeneration.mdem
COMPONENT PACKAGE_GENERATOR

JOB
SOURCE_FILE ./Result_PackingGeneration.mdem
RESULT_FILE ./Result_Simulation.mdem
COMPONENT SIMULATOR
SIMULATOR_TYPE CPU
MODEL_PP ModelPPHertzMindlin
MODEL_PW ModelPWHertzMindlin
SIMULATION_STEP 2e-7
SAVING_STEP 1e-5
END_TIME 1e-4
EXT_ACCEL 0 0 -9.81
SIMULATION_DOMAIN -0.03 -0.03 -0.04 0.03 0.03 0.04

Run Simulation with Modified Material Properties

This example shows how to override density and sliding friction coefficient.

SOURCE_FILE ../InitScenes/CompressionTest.mdem
RESULT_FILE ./Result_CompressionTest.mdem
COMPONENT SIMULATOR
MATERIAL_PROPERTY DENSITY KF6843H8 3000
INTERACTION_PROPERTY SLIDING_FRICTION KF6843H8 KF6843H8 0.1