Simulation

Defines the global simulation parameters, such as simulation time and output settings.

Commands

simulationParameters
{
    t_begin                         0. 
    t_end                           10.
    maxitsteps                      10000000
    energy_transport                false
    surften_model                   NONE
    freesurface                     true
    velcorrScheme	             T_VCORR
    verbosityLevel                  VERBOSITY_STANDARD
    freq_log                        100
    ns_phaseinfo                    20                      
    output_type                     VTUBINARY
    dt_output                       0.01
    t_output_offset                 0.5
    t_output_file                   /path/to/outputtimes.txt
    dt_output_restart               0.1
    t_output_restart_offset         0.5
    t_output_restart_file           /path/to/outputtimes.txt
    dt_output_restart_wallclock     2.5
    dt_phaseinfo                    0.1
    restart_purge                   false
    restart_keep_count              1
    restart                         false
    restart_from_step               200
    output_vel                      false 
    output_wallvel                  false
    output_temp                     false
    output_acc                      false
    output_prtlID                   true
    output_phaseID                  true
    output_rho                      true
    output_press                    true
    output_rank                     false
    output_viscosity                false
    ignoreParticlesOutOfBounds      false                     
    ref_vel_factor                  1.5                       
    dt_simulation                   -1                          
    adhesionmodel                   false                     
    output_data_dir                 /path/to/output           
    restart_from_dir                /path/to/sim/to/restart   
    operationMode                   NORMAL                    
    damping_type                    HARMONIC                  
    interactionscheme               WEIGHTED                  
    APD_coeff                       0.001   
    APD_cutoff_factor               3.0                                            
    RM_freq_rho_reinit              20                        
    RM_rho_filtering                INSTANT
    RM_coeff_vel_limiter            1.25
    wrnFailLevel                    5
    nFXcTandemInterp                true
    valKeychains                    false
    filesys_topo                    AUTO
    print_memusage                  false
    cleandir_opt                    MODIFY
    enforce_operation_order         false
    varvisc_temperature             false
    varvisc_non_Newtonian           false
    output_comp                     true
    output_comp_level               6                 
}

Definitions

Command Contents SI Unit Example
t_begin Time at start of simulation

Default = 0

  
t_end End-time of simulation

Default = 1.0

  
maxitsteps In nanoFluidX, the numerical time-step is calculated internally based on stability criteria using input values like reference velocity. Depending on the resulting time-step and the time to simulate (t_end – t_begin), a huge number of iterations might be necessary. In order to avoid an infinite loop this parameter can be used to stop a simulation after a given number of iterations.
Tip: This parameter is typically used for performance benchmarks where the simulation is performed for a given number of steps.

Default = 1000000000

  
energy_transport This model flag switches on/off the energy equation model. If enabled, additional fields such as temperature are included in the simulation and corresponding phase parameter. Reference values and output flags need to be set.
Options
  • true
  • false (Default)
Related Commands
  • output_temp
  • Energy equation
  • heat_cap
  • heat_cond
  • evolve_temp
  • temp_0
  
surften_model This flag can be used to switch on the surface tension model1 or enable single phase surface tension.
Options
  • NONE (Default)
  • ADAMI
  • SINGLE_PHASE
  • TARTAKOVSKY2016_F1
Warning: If ADAMI, TARTAKOVSKY2016_F1, or SINGLE_PHASE is chosen, an additional parameter in the phase properties must be defined.
Related Options
  • ref_curv
  • surf_ten
  • Multiphase surface tension
  
freesurface This flag prevents the occurrence of negative pressure values due to lack of support in single phase cases.
Options
  • true (Default)
  • false
Tip: In single phase cases, the free surface of the fluid is in contact with a particle vacuum (absence of particles) which in classic SPH formulation would cause unphysical behavior. It is recommended to keep this option set to true.
CAUTION:
Changing this flag without an advanced understanding could have undesired consequences.
Related Commands
  • Free surface formulation
  
velcorrScheme Particle velocity correction schemes, also referred to as reuniformization schemes or shifting schemes, are used to improve particle (discretization point) distribution in nanoFluidX and the quality of results. nanoFluidX uses transport velocity (TV) and artificial particle displacement (APD) methods to produce well arranged particle distributions.

While TV and APD themselves are not tied to a specific interaction scheme, the current implementation in nanoFluidX means that TV is more suited for Weighted interaction scheme and APD is intended for use with Riemann interaction scheme.

Options
  • T_VCORR - When setting interaction scheme to Weighted, it cannot be used with Riemann the interaction scheme. This activates Transport Velocity (TV).
  • AP_VCORR - When setting interaction scheme to Riemann, it cannot be used with the Weighted interaction scheme. This activates Artificial Particle Displacement (APD).

Default = The default value is set according to the interaction scheme.

Related Commands
  • Transport velocity formulation
  
verbosityLevel During a simulation, nanoFluidX prints some log-information about the current status of the simulation. The amount of output can be controlled with this parameter.
Options
  • VERBOSITY_NONE - Minimum amount of output.
  • VERBOSITY_STANDARD (Default) - Current stage of the simulation, actual performance.
  • VERBOSITY_EXPERT - Additional information on particle distribution – helpful for debugging and/or experts only.
  
freq_log This increment gives the frequency of log information, that is, every #freq_log steps the log output is written.

Default = 100

  
ns_phaseinfo This value (integer) determines how often the forces/torques, and other phase information, are measured.
Tip: This command is slightly different from dt_phaseinfo, as dt_phaseinfo determines the frequency of the output. For example, you may want to output dt_phaseinfo every 0.1 s, in the meantime, there might be 10000 simulation steps in that time period. ns_phaseinfo then allows you to specify the number of measurement samples in that period. For example, 100 samples per dt_phaseinfo.
Attention: Changing this value can speed up the simulation substantially, while having a minor impact on the output information quality.

Default = 20 (20 samples per dt_phaseinfo)

  
output_type This parameter defines the type of the output.
Options
  • NOOUTPUT
  • VTK - ASCII format is not maintained
  • VTUIBINARY (Default) - Exports binary format VTK
  • VTUBINARY - Exports binary VTK and coarsely interpolated data in VTI format
  
dt_output This is the time increment when the particle output is written.

Default = 0.1

  
t_output_offset Time delay to start of writing particle data output. For example, setting this command to 0.2 s means that the writing of the particle output begins at 0.2 s.
Note:
  • If set to -1 there will be no effect and output will start from the beginning of the simulation.
  • Offset time is always taken relative to the start/restart time of the simulation. Setting the value to zero has the same effect as setting it to -1.
  • If set to any positive value, that specified value in [s] will be used a delay.
  • No matter what setting, initial (t = 0) and final (t = tfinal) outputs are always written.

Default = -1 (no effect).

  
t_output_file Enables you to specify a file in which the exact times of the desired particle output are specified. The format of the file is a column of desired time outputs with:
  • Absolute or relative path to the file with particle output times.
  • Times provided in the output file are always with respect to the t = 0.
Attention: This command is mutually exclusive with and takes precedent over dt_output and t_output_offset.
  
dt_output_restart Defines how often restart files are output. If you do not want to output restart files, enter -1.
Attention: Restart output is only deactivated if dt_output_restart is non-positive and a file is not provided.

Default = 10*dt_output

  
t_output_restart_offset Delays the start of writing restart output. For example, setting this command to 0.3 s means that the writing of the restart output begins at 0.3 s.

It is similar to t_output_offset, except that the former is referring to the particle output, and the latter to the restart output.

Note:
  • Offset time is always taken relative to the start/restart time of the simulation.
  • Setting the value to zero has the same effect as setting it to -1.
  • No matter what setting, initial (t = 0) and final (t = tfinal) outputs are always written.

Default = -1 (no effect)

  
t_output_restart_file Enables you to specify exact times at which the restarts will be written. The format of the file is a column of desired time outputs with:
  • Absolute or relative path to the file with particle output times.
  • Times provided in the output file are always with respect to the t = 0.
Attention: This command is mutually exclusive with and takes precedent over dt_output_restart and t_output_restart_offset.
  
dt_output_restart_wallclock A wallclock time interval to write recon files, in hours. The acceptable range is between 1 second and 24 hours.

Default = 0.0 (inactive)

  
dt_phaseinfo This is the time increment when the additional phase-info output is written (if any of the phases has print_info == true).

Default = 0.1

  
restart_purge If this switch is set to false, it will keep all the restart files that have been output. Otherwise, if set to true, it will keep only the latest restart point.
Options
  • true
  • false (Default)
Related Commands
  • Restart option
  
restart_keep_count If restart_purge is true, restart_keep_count is the number of restart/continue files to keep. This command is optional.

Default = 1

  
restart Defines if you are continuing a simulation or starting from a restart file.
Options
  • true - Continuation of a previous simulation
  • false (Default) - New run
Related Commands
  • Restart option
  
restart_from_step This specifies from which point does the simulation restart. The restart numbers with the respective times can be found in the OUTPUT folder of the case, in the restart.txt file.

Alternatively, you can use the keyword in the command line upon launching and the code automatically picks up from the last available restart file. For more information, refer to Restart a Simulation in the Run nanoFluidX section.

Related Commands
  • Restart option
  
Output Flags If the particle output is written, the following flags can be used to limit the amount of data that is actually written to the output file. Except for the particle positions, all other variables can be switched on/off for the output. The order of the flags is not important.
output_vel This flag switches on/off the velocity field for the output.
Options
  • true
  • false (Default)
  
output_wallvel This flag switches on/off the velocity field of wall particles for the output.
Options
  • true
  • false (Default)
  
output_temp This flag switches on/off the temperature field for the output.
Options
  • true
  • false (Default)
Warning: When this flag is set to true and energy_transport is set to false, an error occurs.
Related Commands
  • energy_transport
  
output_acc This flag switches on/off the acceleration field for the output.
Options
  • true
  • false (Default)
  
output_prtlID This flag switches on/off the particle ID field for the output. This is a unique integer number for each particle to track the Lagrangian motion in time.
Options
  • true
  • false (Default)
  
output_phaseID This flag switches on/off the phase ID (phase number) of each particle for the output.
Options
  • true (Default)
  • false
  
output_rho This flag switches on/off the density field for the output.
Options
  • true
  • false (Default)
  
output_press This flag switches on/off the pressure field for the output.  
output_rank This flag switches on/off the rank (GPU) of each particle for the output. This information is only necessary if the particle distribution on different ranks (GPUs) is of interest.
Options
  • true
  • false (Default)
  
output_viscosity This flag enables output of viscosity field in the case that either varvisc_temperature or varvisc_non_Newtonian are set to true.
Options
  • true
  • false (Default)
  
ignoreParticlesOutOfBounds Check flag to ensure continuation of the run in case there is a particle out of bounds. If particles are out of bounds the simulation will not stop. If some kind of outlet is specified for the boundaries, the particles will get deleted. Otherwise they will continue to move outside of the domain.
Options
  • true
  • false (Default)
  
ref_vel_factor Factor which specifies how much overhead is added to the maximum detected velocity in order to ensure adequate time step and keep the simulation stable.
Note: This is relevant only if the ref_vel is set automatically by the code.

Default = 1.5

  
dt_simulation Allows for manual override of the internally calculated (recommended) time step.
CAUTION:
Use with extreme caution, especially if using larger than recommended time step.

Default = -1 (Or the value the code calculates as appropriate)

  
adhesionmodel Boolean switch for enabling primitive adhesion models, based on the model of Akinci et al. For more information, refer to Adhesion Model and Single Phase Surface Tension.
Options
  • true
  • false (Default)
  
output_data_dir Specifies a relative or absolute path for the output folder. The data output will be stored in this folder. Format: path/to/directory.

Default = Folder which contains the .cfg file. This is also a reference if relative path is provided.

  
restart_from_dir Specify from which folder should the case be restarted. Format: path/to/the/restart.

Default = Folder which contains the .cfg file. This is also a reference if relative path is provided.

  
operationMode A switch that serves as a shortcut to optimize the solver performance for maximum speed, normal operation, or optimize for accuracy.
Options
  • DESIGN
  • NORMAL (Default)
  • CONSERVATIVE
Attention: A proficient user can achieve either the DESIGN or CONSERVATIVE modes manually by setting the correct parameters. For more information, refer to Operation Modes.
  
damping_type Choice of damping (ramping) function.
Options
  • HARMONIC (Default) - Standard nanoFluidX damping function of hyperbolic tangent type (S-like curve).
  • LINEAR - Function is optional. This command applies to all damping parameters in the simulation.
  
interactionscheme Choice of the particle interaction scheme of the solver.
Options
  • WEIGHTED (Default) - Solver is the same solver encountered in previous versions of nanoFluidX.
  • RIEMANN - Solver is an interaction scheme, which includes Moving Least Square (MLS) gradient corrections and optionally Artificial Particle Displacement (APD). For more information, refer to Particle Interaction Schemes in the Theory Manual.
  
APD_coeff APD particle position correction scheme parameter for intensity of the correction.
Tip: APD is an efficient algorithm for particle regularization.
  • High values (>0.1) of APD will preserve the Shepard coefficient efficiently at 1 within the domain, but may cause other unwanted numerical effects.
  • If the RIEMANN solver is in use for single phase runs, this parameter should be set to 0.0.

Default = 0.001

  
APD_cutoff_factor Determines the radius (as a function of dx) of the sphere of influence of the APD corrections scheme. This factor plays an important role in balancing the intensity of the APD correction and potential local instabilities and therefore consequent behavior of the Riemann solver.
Tip: Best practice is to use a value between 2 and 3. Set as 2.0 to have less local instabilities (hot particles), but less intensity in particle positioning, and 3.0 for stronger APD correction (less particle vacuum), but potentially more local instabilities.

Default = 3.0

  
RM_rho_filtering The density filtering (also referred to as density re-initialization) operation. The density filtering procedure improves the mass-area-density consistency and filters out small-scale pressure oscillations.
Options
  • INCREMENTAL
  • INSTANT (Default)
Important: This command is only applicable to the RIEMANN solver (obsolete when using WEIGHTED).
Tip:
  • For simulations with a physical free surface, the INCREMENTAL filtering scheme is recommended.
  • For multiphase simulations, the INSTANT filtering scheme is recommended.

For more information, refer to Particle Interaction Schemes in the Theory Manual.

  
RM_freq_rho_reinit The frequency (number of timesteps) utilizing the density filtering scheme (selected by the command RM_rho_filtering).

Default = 20

  
RM_coeff_vel_limiter Limiter parameter that sets the upper limit on maximum velocity experienced by a particle.
Attention: Particles whose velocity exceeds the value of the reference velocity, multiplied by the RM_coeff_vel_limiter, will have their velocity reset to the reference velocity value.

Default = 1.25

  
wrnFailLevel Allows you to specify at which level a warning becomes an error and stops the simulation. nanoFluidX has 5 warning levels where 5 is the most severe.

Default = 5 (no warning produces an error)

  
nFXcTandemInterp Enables tandem operation between nanoFluidX and nanoFluidX[c] where nanoFluidX[c] interpolates the data from nanoFluidX as it becomes available in the output. This tandem operation is done through a pipe file (FIFO) that is created inside the working case folder.
Options
  • true (Default)
  • false

For more information, refer to the Theory Manual.

  
valKeychains Keychain validator compares the keychains in the cfg file with valid nanoFluidX keychains, when activated. Keychain validator is meant to help address typographical errors in the .cfg file.
Options
  • true
  • false (Default)
  
filesys_topo Defines the file system topology for multi-node runs.
Options
  • AUTO - Determined automatically
  • SHARED - All nodes share the same file system
  • DISTRIBUTED - Every node writes to its own, local file system
  
print_memusage Prints memory usage (host/device) in log output.
Attention: The derivation of the values slightly differs between device on host based on the information available. The device value is calculated from the difference between total memory on a single GPU and the amount of free memory on that GPU. This gives the correct value for all supported configurations.

For the unsupported case of a GPU being oversubscribed and multiple MPI ranks residing on it, the value is the sum of all processes on this MPI rank. For host memory, the amount of memory used is represented by the resident set size of every MPI rank. The amount of memory is correct although multiple MPI ranks usually reside in the shared RAM on a single machine.

Additionally, if there is not enough host memory available and memory is swapped to the disk, the amount of swapped memory is not included in the printed value.
Default =
  • [true] if VERBOSITY_EXPERT
  • [false] if VERBOSITY_STANDARD
  
cleandir_opt Treatment of output data directory in a clean run.
Options
  • MODIFY (Default) - Append simulation start time to original directory name and make a new directory with this modified name
  • PURGE - Overwrite the content of the previous run
  • BREAK - Display an error in case of a non-empty previous run directory
  
enforce_operation_order Enforces summation order in the GPU calculations and effectively allows for full run reproducibility provided the same hardware and software platform.
Options
  • true
  • false (Default)
Note: When enabling operation order, you can expect a small computational penalty ranging from 0 to 20 percent reduction in performance. The exact performance drop is difficult to generalize as it depends on the exact numerical setup and number of particles on each of the GPUs.
  
varvisc_temperature Set to true to request temperature dependent viscosity.
Options
  • true
  • false (Default)
Attention:
  • Energy equation must be active (energy_transport set to true) and viscosity models section must be present.
  • This command is mutually exclusive with varvisc_non_Newtonian.
  
varvisc_non_Newtonian Enables non-Newtonian behavior modeling.
Options
  • true - Request shear stress dependent viscosity
  • false (Default)
Attention:
  • Viscosity models section must be present.
  • This command is mutually exclusive with varvisc_temperature.
  
output_comp Enables compressed binary data output.
Options
  • true (Default) - Activates compressed output
  • false - Writes uncompressed data
  
output_comp_level Output data compression level.
Options
  • Integer value ranging from 0 to 9
Default = 6
  

References

1 S. Adami, Modeling and Simulation of Multiphase Phenomena with Smoothed Particle Hydrodynamics, Chair of Aerodynamics and Fluid Mechanics, Technical University of Munich, 2014
2 S. H. X. a. A. N. Adami, "Simulating three-dimensional turbulence with SPH,“ in Proceedings of the Summer Program 2012, Stanford University, Paolo Alto, 2012