Simulation Parameters

The first section defines the global simulation parameters such as simulation time and output settings.

simulationParameters
{
    t_begin                         0. 
    t_end                           10.
    maxitsteps                      10000000
    energy_transport                false
    viscTempCoupling                false
    surften_model                   NONE
    freesurface                     true
    transportvelocity               true
    verbosityLevel                  VERBOSITY_STANDARD
    freq_log                        100
    ns_phaseinfo                    100                      
    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              5
    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
    ignoreParticlesOutOfBounds      false                     
    ref_vel_factor                  1.5                       
    dt_simulation                   -1                          
    aeroViscMode                    NOMODE                    
    aeroViscCoeff                   10.0                      
    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.05   
    APD_cutoff_factor               3.0                                            
    RM_freq_rho_reinit              -1                        
    RM_rho_filtering                INSTANT
    RM_coeff_vel_limiter            1.25     
    wrnFailLevel                    5        
    nFXcTandemInterp                true
    valKeychains                    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 the 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 usually 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 ON, 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
viscTempCoupling
This is a Boolean switch that enables temperature-viscosity coupling. It can only be turned on, if the energy_transport flag is turned on, otherwise it makes no sense, as the temperature is not even calculated.
If this switch is turned on, the fluid viscosity is determined by the specified models and the dyn_visc parameter from the phase section is ignored. The temperature-viscosity models are defined in the Viscosity-temperature dependence models section.
Also, please note that if this flag is on, then all fluids in the domain must have their viscosities defined by using the Viscosity-temperature dependence models section.
Related options/commands: ref_visc, Viscosity-temperature dependence models
Options: true / false
Default: false
surften_model
This flag can be used to switch on the surface tension model according Adami et al. 1 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
Default: NONE
freesurface
This flag essentially prevents 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 what we refer to as “particle vacuum” (absence of particles) which in classic SPH formulation would cause unphysical behavior. Generally, we recommend keeping this option set to true at all times, unless you are familiar with the consequences of turning it off.
Related options/commands: Free surface formulation
Options: true / false
Default: true
transportvelocity
This flag enables the so called transport velocity formulation of Adami. 1 Transport velocity has a series of beneficial influences on the numerical behavior of the SPH method. It introduces a velocity correction term which actively keeps particle distribution isotropic and prevents the pairing instability as well. In one work by Adami et al. 2 it is speculated that transport velocity can behave essentially like a turbulence model.
Related options/commands: Transport velocity formulation
Options: true / false
Default: true
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, i.e. 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 (e.g. 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: 5 (5 samples per dt_phaseinfo)
output_type
This parameter defines the type of the output.
Options: NOOUTPUT / VTK / VTUIBINARY
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).
Defult: 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
How often do you want to output restart files? If you do not want to output restart, you should enter -1.
Restart output is only deactivated if dt_output_restart is non-positive and no file is 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.
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 “last” in this command the code will automatically pick up from the last available restart file.
Related options/commands: Restart option
output_vel
If 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. Note, 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
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)
aeroViscMode
Switch for enabling coupling between aeration of oil and apparent viscosity of the oil.
Options: NOMODE, LOCAL and GLOBAL
Default: NOMODE
aeroViscCoeff
Linear coefficient in the aeration-viscosity coupling model. It effects how much more viscous will the fluid get as a function of oil-air mixing.
Default: 0.0
adhesionmodel
Boolean switch for enabling primitive adhesion models, based on the model of Akinci et al.
Options: true / false
Default: false
output_data_dir
Specify 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
Switch which serves as a shortcut to optimize the solver performance for maximum speed, normal operation, or optimize for accuracy.
Proficient user can achieve either the DESIGN or CONSERVATIVE modes manually by setting the correct parameters.
Options: DESIGN, NORMAL, CONSERVATIVE
Default: NORMAL
damping_type
Choice of the damping (ramping) function.
Options: HARMONIC and LINEAR
  • HARMONIC is the 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 and RIEMANN
  • 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).
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.
Should be set to 0.0 if using the RIEMANN solver for single phase runs.
Default: 0.05
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
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 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 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.
More information can be found in the Theory and Advanced Features chapter.
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

1 S. Adami, Modeling and Simulation of Multiphase Phenomena with Smoothed Particle Hydrodynamics, Lehrstuhl für Aerodynamik und Strömungsmechanik, Technische Universität München, 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