output_settings command
Purpose
Command reponsible for generating output.
Note
This command is supported by Aspherix GPU.Syntax
output_settings keyword value
Zero or more keyword/value pairs may be appended, which can be categorized by their application: particle, geometry, interaction, eulerian, and general
Particle related keywords:
write_particles value = yes or no yes = output particle data no = do not output particle data particle_properties value = none or all or {prop_1, prop2, ...} none = output only the particle position and, in case of superquadrics, the shape all = output all the available particle properties prop_i = per-particle property to be output particle_properties_exclude value = {prop_1, prop2, ...} prop_i = per-particle property to be excluded from output write_overlay_mesh value = yes or no yes = output the overlay mesh (STL/OBJ) for each particle (as defined via the particle_template command) no = do not output overlay mesh write_meshed_particles value = yes or no yes = output meshed particle data no = do not output meshed particle data additional_particle_output value = stl, obj, vtk, vtp, none stl = write additional particle output in stl format obj = write additional particle output in obj format vtk = write additional particle output in vtk format vtp = write additional particle output in vtp format none = do not write additional particle output
Geometry related keywords:
write_meshes value = yes or no yes = enable additional output for imported meshes no = disable the additional mesh output meshes value = {mesh_1, mesh_2, ...} mesh_i = name of the mesh to be output mesh_properties values = {mp_1, mp_2, ...} mp_i = property to be output (see the table and description below) mesh_properties_exclude values = {mp_1, mp_2, ...} mp_i = property to be excluded from output (see the table and description below)
Interaction related keywords:
write_particle_contact_network value = yes or no [default] yes = enable additional output of inter-particle properties for the particle contact network no = disable additional output of inter-particle properties for the particle contact network write_particle_bond_network value = yes [default] or no yes = enable additional output of inter-particle properties for the particle bond network no = disable additional output of inter-particle properties for the particle bond network write_wall_contact_network = yes or no [default] yes = enable additional output of particle-wall properties for the wall contact network no = disable additional output of particle-wall properties for the wall contact network write_wall_bond_network = yes [default] or no yes = enable additional output of particle-wall properties for the wall bond network no = disable additional output of particle-wall properties for the wall bond network particle_network_command_ids value = {id_1, id_2, ...} id_i = id of a calculate particle_contact_network or calculate particle_bond_network command wall_network_command_ids value = {id_1, id_2, ...} id_i = id of a calculate wall_contact_network or calculate wall_bond_network command
Eulerian related keywords:
write_eulerian_fields* value = yes or no yes = any eulerian fields from spatial_averaging commands will be included in the output [default] no = no eulerian fields will be included eulerian_fields value= {e_1, e_2, ...} e_i = name of a spatial_averaging command to be written
General keywords:
id value = command-ID command-ID = user-assigned name for the command call write_every_time value = period period = time interval between two consecutive output ascii value = yes or no yes = output data in ascii format no = output data in binary format compressor value = none [default], zlib, lz4 none = binary output data is not compressed zlib = binary output data is compressed with zlib lz4 = binary output data is compressed with lz4 legacy_timeseries value = yes or no yes = use time step numbers in the pvd file no = use physical time in the pvd file [default] file value = filename filename = output file(s) name folder value = foldername foldername = (relative) output folder/directory name write_decomposition value = yes or no yes = the domain information will contain the processor decomposition [default] no = the domain will be a simple rectangular block mode value = modify [default] or replace modify = change (add to) the existing output_settings command replace = replace the existing output_settings command with a new one parallel value = yes or no yes = output is written in parallel (based on value of number_of_output_processors no = only one processor writes the data number_of_output_processors value = nout nout = number of processors which will write data
Examples
output_settings id out_set meshes {box, chute} write_wall_contact_network yes write_particle_contact_network yes file post/out_*.vtm
output_settings folder sim_radius_0.4
output_settings particle_properties {id, x, y, z, radius, vx, vy, vz, id_cal1}
Description
The output_settings command creates all required commands (computes, fixes, dump commands and status settings) to output simulation data for particles, geometries, interactions and eulerian fields.
Particle output
By default the output_settings command saves all commonly available particle properties for graphical postprocessing. This includes information such as id, material type, radius, density, mass, velocity, angular velocity, force, torque, orientation (for superquadrics and facetted particles) and shape (for superquadrics). In addition to that also per-particle results from calculate commands, e.g., particle residence time, or physics-model related properties such as temperature and surface liquid content are saved. A list of common particle properties can be found below.
The keyword particle_properties allows to control the per-particle output properties:
particle_properties none |
only particle position, radius or shape + orientation (superquadric particles) |
particle_properties all |
all available particle properties (default) |
particle_properties {list_of_properties} |
user defined list of particle properties (see list) |
With particle_properties_exclude all available particle properties are writte except the properties specified in the list.
The output of particle data can be disabled by setting write_particles no and this overrides any option specified by the particle_properties or particle_properties_exclude keyword.
Replacing particles by meshes:
With write_overlay_mesh yes a particle can be replaced by another STL mesh file in the output. It is therefore necessary to define an overlay_mesh_file for all particle templates which will replace the original particle with an STL/OBJ file. Please note that the replacement only happens for postprocessing, all calculations will be carried out with the original particles. If the concave_decomposition command has been used, the write_overlay_mesh will output the original concave file. Note that for both cases write_meshed_particles yes will be set automatically.
If write_meshed_particles yes, additional_particle_output can be used to specify the additional particle output format (written to a separate file). Note that if additional_particle_output is set to anything else than none, write_meshed_particles yes will be set automatically (a warning will be shown). Furthermore, if write_meshed_particles no is set, additional_particle_output none will be set automatically (a warning will be shown). The write_meshed_particles can be used to specify if meshed particles are be written. The default is to just write a single vertex at the center of the mass of the particles and the particles are then visualized by a post-processing tool. The write_meshed_particles directly writes a triangulated mesh which significantly increases the memory requirements of the output data.
Note
If write_overlay_mesh yes is used, it is necessary to add save_template_information yes (which is the default value) to all insertion commands
Particle output properties:
The number of available particle properties varies from case setup to case setup. This is a basic list of properties that always exists:
id = particle ID
radius,diameter = radius,diameter of spherical particle
type = material type (integers)
mass = particle mass
x,y,z = coordinates of the particle center
vx,vy,vz = particle velocities
omegax,omegay,omegaz = angular velocity of spherical particle
fx,fy,fz = forces on particles
tqx,tqy,tqz = torque on finite-size particles
Here are some examples for particles properties, whose existence depends on the particle shapes of the used material, physical properties or additional calculate commands:
mux,muy,muz = orientation of dipole moment of atom (if particle_shape keyword magnetic = yes and addforce/magnetic is active) mu = magnitude of dipole moment of atom angmomx,angmomy,angmomz = angular momentum of aspherical particle shapex, shapey, shapez = semi-axes for superquadric particles blockiness1, blockiness2 = blockiness parameters for superquadric particles TENSOR = default orientation output of superquadric and facetted particles, suppresses output of quaternions quat1, quat2, quat3, quat4 = quaternion components for superquadric and facetted particles quat = quaternion components for superquadric and convex particles as a 4-element vector id_ID = per-particle vector calculated by a command with ID id_ID[N] = Nth column of per-particle array calculated by a command with ID v_name = per-particle vector calculated by an atom-style variable with name id_Temp = particle temperature (e.g., when enable_heat_transfer is active) id_heatFlux / id_heatSource = heat fluxes, sources of particles id_surfaceLiquidContent = liquid content on particle surface (e.g., when liquid transport is active) id_liquidFlux / id_liquidSource = liquid flux / liquid source via surface films calculated by a liquid bridge model
Temperature, heat flux and surface liquid content are just a few examples for output that is generated by different models. When applying complex physical models, please check the respective documentation regarding more information about possible output.
Mesh output
With write_meshes the output of all imported stl meshes and their properties (e.g. wear) is enabled automatically. The default value for write_meshes is yes, writing meshes can be disabled by setting the value to no. If no meshes are specified in the list, all stl meshes are written but none of their properties are saved.
The pre-requisite for property output is that the meshes are added to the meshes list. If no mesh_properties are given, all writeable properties (of type double) are written to output files for all meshes in the meshes list. For all other meshes no mesh properties are written.
With mesh_properties_exclude all writable properties (of type double) will be written, except the properties in the list. Mesh properties with an other type than double can always be written by including them explicitly to the mesh_properties list. Common mesh properties (which are automatically written when available) and their requirements (in order to make them available) are given in the table below:
Mesh output properties:
mesh_property |
prerequisite |
description |
|---|---|---|
v (or: vel) |
velocity |
|
f |
force |
|
sigma_n (or: stress) |
normal stress |
|
sigma_t (or: stress) |
tangential (shear) stress |
|
area |
surface area |
|
edgeLen |
length of the edges |
|
surfaceNorm |
surface normal vector |
|
deformation (or: node_deformation) |
enable_fem_coupling |
node deformation (total) |
deformation_step (or: node_deformation_step) |
enable_fem_coupling |
node deformation (delta) |
*id_insertion*_tag |
enable ‘tag’ via material interaction properties |
tagging of particles inserted by id_insertion |
displace |
node displacement |
|
average_normal_stress |
average normal stress |
|
average_shear_stress |
average shear stress |
|
moving_average_normal_stress |
moving average normal stress (in time) |
|
moving_average_tangential_stress |
moving average tangential stress (in time) |
|
contact_area |
relative area in contact with particles (overlap area) |
|
contact_area_abs |
absolute area in contact with particles (overlap area), averaged in time |
|
mass_deleted_per_area |
deleted mass |
|
n_deleted_per_area |
deleted number of particles |
|
Temp |
temperature |
|
heatFlux |
heat flux |
|
heatFluxExternal |
external heat flux |
|
heatFluxExteriorConduction |
heat flux due to exterior conduction |
|
heatFluxParticleConduction |
heat flux due to particle conduction |
|
heatFluxParticleRadiation |
heat flux due to particle radiation |
|
heatFluxSource |
heat flux due to a source |
|
heatFluxWallConduction |
heat flux due to wall (internal) conduction |
|
liquidContent |
liquid content |
|
liquidFlux |
liquid flux |
|
wear |
total wear volume |
|
id |
id of each mesh triangle. Appears in Paraview as ‘element_id’ |
When other mesh properties (like id, stresscomponents (force divided by area), owner (for parallel simulations), aedges (number of active edges), acorners (number of active corners) or nneighs (number of neighbors) and mesh_module specific mesh properties (see the documentation on the mesh_module) are required, a full list of mesh_properties can be provided by the user. In that case only the mesh properties in the list will be written, other mesh properties are not automatically added.
Interaction output
The optional keywords write_particle_contact_network and write_wall_contact_network add, respectively, the output of all particle-particle and particle-wall contact (force) networks. For details see the commands calculate particle_contact_network and calculate wall_contact_network. These options are disable by default, but if the particle / wall contact network output is enabled all available particle / wall contact networks will be written (and created automatically if none was found).
The optional keywords write_particle_bond_network and write_wall_bond_network add, respectively, the output of all particle-particle and particle-wall bond networks. For details see the commands calculate particle_bond_network and calculate wall_bond_network. If the particle / wall bond network output is enabled (as it is by default if there are any bonds), all available particle / wall bond networks will be written (and created automatically if none was found).
However, by using the keyword particle_network_command_ids it is possible to specify a list of particle contact and bond command ids whose output will be written to file. The same holds for the walls, where by using the keyword wall_network_command_ids it is possible to specify a list of wall contact and bond command ids whose output will be written to file. This way, the exact particle and bond networks to to be written can be customized / limited.
Note
The calculate commands mentioned above need to include the IDs of the
particles (property name ids) in order to be used with
output_settings.
Eulerian output
If the write_eulerian_fields keyword is set to yes the information from Eulerian fields (see calculate spatial_average, calculate spatio_temporal_average) will be written to the output.
If the eulerian_fields keyword is not set all such fields will be written as long as the original command does not contain any dedicated output (e.g. using the file keyword). If the eulerian_fields keyword is set to a list of ids (of the calculate commands listed above) then only those in the list will be written.
General keywords
Aspherix automatically assigns an ID to the output_settings, that can be overwritten using the id keyword.
The output_settings command automatically triggers a default status_style command. The default settings for the status_style are time, step, atoms, ke, c_rke, cu and check_timestep if available terminal, the data file simulation_data_aspherix.csv contains all these quantities and everything else (e.g., forces on meshes, …). These default settings can be over-written by adding a status_style command with the desired settings after the output_settings command.
Note
In case a status_style is set before the output_settings command, then the output on the terminal will be according to that style.
The write_every_time keyword defines the frequency of the
data output, and the file keyword can be used to set the output
filename. The asterisk (*) is a wildcard that will be replaced by the
timestep number at which the file was written - for example, a
filename post/out_*.vtm will result in data files with names
post/out_1000.vtm, post/out_2000.vtm etc. Another way to
change the output location is to use folder, which will only change
the output folder/directory (and use the default filename). Note that
folder can not be combined with file, and should not start with a slash
in order to make it a relative location.
The output_settings command automatically writes the domain decomposition information to the output. Each processor subdomain will be represented by a cell which will carry information about the processor id and the number of local particles. By setting write_decomposition this can be switched off.
The ascii keyword controls whether output files are written in ascii or binary format. The former is more human-readable, but also results in significantly larger files.
The compressor keyword, which can only be used when writing binary data files, controls how the output files are compressed. This might result in significantly smaller files, at the cost of compressing the data during run time.
By default the pvd file will use the real time for the timestep variable in Paraview. If legacy_timeseries is yes, the pvd file will use the time step numbers for the timestep variable.
By default the output is written in parallel and each processor writes the data it currently owns. This can lead to a lot of work on output nodes on clusters, particularly if running on several hundreds of processors. In order to reduce the load the parallel keyword can be used and if set to no then only one processor will write all the data and all the others will send their data to that particular processor. That can obviously lead to a congestion on the writing processor. So as a middle ground it is possible to use the number_of_output_processors keyword which allows to set a value between 1 and the number of MPI processors used in the current simulation. So you could for example run your simulation on 512 processors but only write on 16 of them. All others would send their data to the closest processor that is writing, thus reducing the load on the output nodes while at the same time not putting all the burden on a single processor.
When using more than one output_settings command in a simulation, the keyword mode can be used to switch between modifying and replacing the existing (previous) output_settings command. For more information on that have a look at the “Additional information” section below.
Additional information
An aspherix_simulation.pvd file is automatically generated listing all the .vtm files (one for each output time) generated during the simulation. Each simulate command will also update any existing output_settings command, which will ensure that automatically added meshes and particle properties are up to date. Furthermore, it is possible to modify an existing output_settings command by redefining it again (it will automatically use the default mode modify). Any omitted keyword/values will remain the same (as defined in the original output_settings command), and only the keyword/values specified in the new output_settings command will be modified. To completely replace an earlier defined output_settings command, one can use mode replace in the definition of the new output_settings command.
Restrictions
This command needs to follow the simulation_timestep command.
Warning
The settings write_particle_contact_network yes and write_wall_contact_network yes
do not have full GPU support.
Default
id = output_setting, write_every_time = dt_out(defined via write_output_timestep) * dt(defined via simulation_timestep), write_particles = yes, additional_particle_output = no, write_meshed_particles = no, write_overlay_mesh = no, write_particle_contact_network = no, write_wall_contact_network = no, write_meshes = yes or ascii = no or compressor = none or file = post/dump_particle_*.vtm, mode = modify, parallel = yes, number_of_output_processors = number of total MPI processors