Simulation

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

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                 
}
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.
Note: 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.
Related Options/Commands: output_temp, Energy equation, heat_cap, heat_cond, evolve_temp, temp_0
Options: true / false
Default: false
surften_model
This flag can be used to switch on the surface tension model, according to Adami et al, or enable single phase surface tension. If ADAMI or SINGLE_PHASE is chosen, additional parameter in the phase properties need to be defined.
Related Options/Commands: ref_curv, surf_ten, Multiphase surface tension
Options: NONE / ADAMI / SINGLE_PHASE / TARTAKOVSKY2016_F1
Default: NONE
freesurface
This flag essentially prevents the occurrence of negative pressure values due to lack of support in single phase cases. 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. Changing this flag without an advanced understanding could have undesired consequences.
Related Options/Commands: Free surface formulation
Options: true / false
Default: true
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 subsequently the quality of the results obtained. Specifically, nanoFluidX uses transport velocity (TV) and artificial particle displacement (APD) methods to produce well arranged particle distributions. While TV and APD themselves are not necessarily 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.
Related Options/Commands: Transport velocity formulation
Options: T_VCORR/AP_VCORR
Default: The default value is set according to the interaction scheme:
T_VCORR
When setting interaction scheme to Weighted. Cannot be used with Riemann interaction scheme. Activates Transport Velocity (TV).
AP_VCORR
When setting interaction scheme to Riemann. Cannot be used with Weighted interaction scheme. Activates Artificial Particle Displacement (APD).
verbosityLevel
During a simulation, nanoFluidX prints some log-information about the current status of the simulation. Depending on this parameter the amount of output can be controlled.
VERBOSITY_NONE
Minimum amount of output.
VERBOSITY_STANDARD
Current stage of the simulation, actual performance.
VERBOSITY_EXPERT
Additional information on particle distribution – helpful for debugging and/or experts only.
Options: VERBOSITY_NONE / VERBOSITY_STANDARD / VERBOSITY_EXPERT
Default: VERBOSITY_STANDARD
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 will the forces/torques and other phase information be measured. It is 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).
Playing with 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 / VTUIBINARY / VTUBINARY
Currently supported outputs are: NOOUTPUT (no output), VTK (ASCII format - NOT MAINTAINED), VTUBINARY (Binary format VTK), VTUIBINARY (exports binary VTK + a coarsely interpolated data in the form of a VTI format).
Default: VTUBINARY
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.
If set to -1 there will be no effect and output will start from the beginning of the simulation.
If set to any positive value, that specified value in [s] will be used a delay.
Example: setting this command to 0.2 s means that the writing of the particle output begins at 0.2 s.
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.
Note: No matter what setting, initial (t = 0) and final (t = tfinal) outputs are always written. Default: -1 (no effect).
t_output_file
Using the command (providing the particle output file) enables the user to specify a file in which the exact times of the desired particle output are specified.
The format of the file is simply a column of desired time outputs.
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.
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.
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
Delay start of writing restart output.
Command is similar to t_output_offset, except that the former is referring to the particle output, and the latter to the restart output.
Example: setting this command to 0.3 s means that the writing of the restart output begins at 0.3 s.
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.
Note: No matter what setting, initial (t = 0) and final (t = tfinal) outputs are always written.
Default: -1 (no effect)
t_output_restart_file
This is a similar command to t_output_file. Using this command enables the user to specify exact times at which the restarts will be written.
The format of the file is simply a column of desired time outputs.
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.
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.
Related Options/Commands: Restart option
Options: true / false
Default: false
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
Is this run a continuation of a previous simulation? Is it starting from a restart file? If it is, then set to true. If it is a new run, set it to false.
Related Options/Commands: Restart option
Options: true / false
Default: false
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, one can use the keyword in the command line upon launching and the code will automatically pick up from the last available restart file (see Run nanoFluidX > Restart a Simulation section for more details).
Related Options/Commands: Restart option
output_vel
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.
This flag switches on/off the velocity field for the output.
Options: true / false
Default: false
output_wallvel
This flag switches on/off the velocity field of wall particles for the output.
Options: true / false
Default: false
output_temp
This flag switches on/off the temperature field for the output.
Keep in mind that setting this flag to true, while leaving the energy_transport set to false will result in an error.
Related Options/Commands: energy_transport
Options: true / false
Default: false
output_acc
This flag switches on/off the acceleration field for the output.
Options: true / false
Default: false
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: false
output_phaseID
This flag switches on/off the phase ID (phase number) of each particle for the output.
Options: true / false
Default: true
output_rho
This flag switches on/off the density field for the output.
Options: true / false
Default: false
output_press
This flag switches on/off the pressure field for the output.
Options: true / false
Default: false
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: false
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: false
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: false
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.
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.
Note: Use with extreme caution, especially if using larger than recommended time step.
Default: -1 (whatever 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: false
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.
A proficient user can achieve either the DESIGN or CONSERVATIVE modes manually by setting the correct parameters. For more information, refer to Operation Modes.
Options: DESIGN, NORMAL, CONSERVATIVE
Default: NORMAL
damping_type
Choice of damping (ramping) function.
Options:
HARMONIC
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.
Default: HARMONIC
interactionscheme
Choice of the particle interaction scheme of the solver.
Options:
WEIGHTED
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 details please see Theory > Solver Features > Particle Interaction Schemes
Default: WEIGHTED
APD_coeff
APD particle position correction scheme parameter for intensity of the correction.
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.
Best practice advice is to use a value between 2 and 3.
2.0 for having less local instabilities (hot particles) but less intensity in particle positioning and 3.0 for stronger APD correction (less particle vacuum), but potentially leading to 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.
This command is applicable only to the RIEMANN solver (obsolete when using WEIGHTED).
Options: INCREMENTAL and INSTANT For more details please see Theory > Solver Features > Particle Interaction Schemes
For simulations with a physical free surface, it is recommended to use the INCREMENTAL filtering scheme. For multi-phase simulations, it is recommended to use the INSTANT filtering scheme.
Default option: INSTANT
RM_freq_rho_reinit
The frequency, that is, number of timesteps, of utilizing the density-filtering scheme (selected by the command RM_rho_filtering).
Default number: 20
RM_coeff_vel_limiter
Limiter parameter which sets the upper limit on the maximum velocity experienced by a particle.
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 number: 1.25
wrnFailLevel
nanoFluidX has improved warning information such that it includes 5 different warning levels, going from 0 as benign to 5 as severe.
By using this command the user can specify at which level does a warning become an error and stops the simulation.
Default: 5 (no warning produces an error)
nFXcTandemInterp
Setting this command to true enables tandem operation between nanoFluidX and nFX[c], where nFX[c] in that case, interpolates the data from nFX as it becomes available (output).
This tandem operation is done through a pipe file (FIFO) that is created inside the working case folder.
For more information, refer to the Theory Manual.
Default: true
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.
Default: false
filesys_topo
Define filesystem topology for multi-node runs.
Options:
AUTO
Determine automatically.
SHARED
All nodes share the same filesystem.
DISTRIBUTED
Every node writes to its own, local filesystem.
Note: If AUTO is selected, the solver will attempt to determine the topology automatically (SHARED or DISTRIBUTED), which will also be shown in the log.
Default: AUTO
print_memusage
Prints memory usage (host/device) in log output.
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 will be 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 or [false] if VERBOSITY_STANDARD
cleandir_opt
Treatment of output data directory in a clean run.
Options:
MODIFY
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.
Default: MODIFY
enforce_operation_order
This command enforces summation order in the GPU calculations and effectively allows for full run reproducibility provided the same hardware and software platform.
Enabling operation order the user can expect a small computational penalty ranging from 0 to 20% 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 GPU's.
Default: [false]
varvisc_temperature
Set to true to request temperature dependent viscosity.
Energy equation must be active (energy_transport set to true) and viscosity models section must be present.
Cannot be activated simultaneously with varvisc_non_Newtonian.
Options: true / false
Default: false
varvisc_non_Newtonian
Set to true to request shear stress dependent viscosity (enable non-Newtonian behavior modeling).
Viscosity models section must be present.
Cannot be activated simultaneously with varvisc_temperature.
Options: true / false
Default: false

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 Univeristy, Paolo Alto, 2012