simulate command
Purpose
Command for defining the total runtime of the simulation.
Note
This command is supported by Aspherix GPU.Syntax
simulate mode mode_value keyword arg
mode = optional keyword
mode_value = fixed_time or until_filled or until_settled or until_condition_reached (default value: fixed_time)
Mode specific syntax
mode_style: fixed_time
one of the following time_style/time_value pairs must be appended:
* time_style = time or target_time or time_steps or target_time_steps * time_value = T * T = simulation time (or time-step) interval or simulation end time (or time step)
mode_style: until_filled
one or more keyword/arg pairs may be appended
keyword = filling_region (obligatory keyword) or check_convergence_every_time or mass_threshold or velocity_threshold
filling_region value = region-ID
region-ID = ID of the region where the particles will be generated
check_convergence_every_time value = ct
ct = time interval (in time units) at which convergence check is conducted (default value: 0.05)
mass_threshold value = mt
mt = mass value (in mass units) that is used as break-off criterion (default: 10 times mass of smallest particle)
velocity_threshold value = vt
vt = velocity (in velocity units) that is used as break-off criterion (default: 1e-3)
mode_style: until_settled
one or more keyword/arg pairs may be appended
keyword = filling_region or check_convergence_every_time or velocity_threshold
filling_region value = region-ID
region-ID = ID of the region where the particles will be generated (default: entire simulation domain)
check_convergence_every_time value = ct
ct = time interval (in time units) at which convergence check is conducted (default value: 0.05)
velocity_threshold value = vt
vt = velocity (in velocity units) that is used as break-off criterion (default: 1e-3)
mode_style: until_condition_reached
one or more keyword/arg pairs may be appended
keyword = condition_id or check_convergence_every_time
condition_id value = condition-ID (obligatory keyword)
condition-ID = name of the boolean-style variable containing the condition for stopping the simulation.
check_convergence_every_time value = ct
ct = time interval (in time units) at which convergence check is conducted (default value: 0.05)
Examples
simulate time 1.0
simulate target_time 10.0
simulate time_steps 100000
simulate target_time_steps 1000000
simulate mode fixed_time time 1.0
simulate mode until_filled filling_region body
simulate mode until_settled
simulate mode until_settled filling_region myRegion velocity_threshold 0.01
variable my_condition boolean "ke(all,insertion_region) <= 0.001"
simulate mode until_condition_reached condition_id my_condition check_convergence_every_time 0.1
Description
If no mode is selected, the fixed_time mode is used automatically. One of the time keywords must be set in that case (see below).
mode_style: fixed_time
Run or continue a simulation for a specific time interval (or for a specific number of time steps) or up to a specific time instant (or up to a specific time step). This mode is the standard behaviour of the simulate command.
The time keyword allows to run a simulation over a time interval T. In a similar way, the time_steps keyword allows to run a simulation for a number of time steps T.
The target_time keyword allows to perform a run starting at the current time up to the specified time T. In a similar way, the target_time_steps keyword allows to perform a run starting at the current time step up to the specified time step T. E.g., if the current run time is 1 second and “simulate target_time 10.0” is used, then an additional 9 seconds will be run.
This can be useful for very long runs on a machine that allocates chunks of time and terminate your job when time is exceeded. If you need to restart your script multiple times (reading in the last restart file), you can keep restarting your script with the same run command until the simulation finally completes.
Finally, a value of T = 0 is acceptable; only the status of the system is computed and printed without performing a timestep. Since this also allows certain commands to compute values (such as calculate min/max) this can be useful to fill variable values.
mode_style: until_filled
This mode is particularly written for cases where a single region is to be filled with granular material. It is assumed that an insertion command of mode pack is used to insert a first portion of particles and that one or more insertion commands of style stream are used to add missing material. Applying the command to other configurations might work as well but this is case dependent and cannot be guaranteed.
In this mode the simulation runs until a certain region (defined by the filling_region keyword) is full (i.e., until the change of mass falls under a certain threshold and at least mass_threshold amount of mass is inside the region). The user can select the frequency at which convergence is checked, using the check_convergence_every_time keyword. The default value is a check every 0.05 time units. As soon as the change of mass in a region falls below the mass_threshold at a “check-point” all insertion commands are deleted and a settling process of the length of 2 times the check_convergence_every_time-interval is started. After this the excess material (i.e. all particles outside the filling region) is removed. Finally, the simulation is continued until the particles kinetic energy has settled down sufficiently. This is equivalent to the until_settled algorithm shown below.
The mass_threshold is, per default, computed from the number of particles currently found in the filling_region and the particle properties specified in the relevant particle_template command commands, and should work for most situations and particle shapes. If desired it can also be set manually. If you choose to do so, make sure that the insertion command provides enough mass to reach the threshold: our experience shows that at least
is necessary to ensure proper filling of the domain. Note that the actual massrate can be lower than the requested massrate in the insertion command.
Note
Make sure that the distance between the insertion faces of all stream commands and the filling_region is large enough. It should be at least 4x the bounding sphere radius of the largest particle in the distribution.
Note
mode until_filled requires that you enable gravity.
mode_style: until_settled
This mode is particularly written for cases where an initial particle bed is created by a settling process. It is assumed that an insertion command of style pack is used to create a particle packing that settles under the influence of gravity. The simulation is completed as soon as the kinetic energy inside a region (defined through the keyword insertion_region) or within the entire simulation domain (default setting) falls below a certain threshold value.
The velocity_threshold keyword can be used to set the break-off criterion (ke_thres = 1/2*mass*velocity_threshold*velocity_threshold), its default value is 0.001.
The user can select the frequency at which convergence is checked, using the check_convergence_every_time keyword. The default value is a check every 0.05 time units.
Note
mode until_settled requires that you enable gravity.
mode_style: until_condition_reached
After running for an initial time interval, that is equal to the value specified by the check_convergence_every_time keyword, the simulation will run until the boolean-style variable specified by the keyword condition_id is evaluated to true. The value of the boolean variable is checked every check_convergence_every_time seconds.
If the commands write_output_timestep or write_to_terminal_timestep are used, their values should be equal to check_convergence_every_time.
Restrictions
The specified time is restricted in such a way that the resulting number of time steps fits in a signed 32-bit integer, so you are limited to slightly more than 2 billion steps (2^31) in a single run. However, you can perform successive runs to run a simulation for any number of steps (ok, up to 2^63 steps).