Syntax:
custom style action args ... action args ...
create args = cname datatype Nc
cname = name of custom vector or array to create and initialize with zeroes
datatype = int or float = for integer or floating point values
Nc = 0 for a vector (single value), Nc >= 1 for an array (one or more values)
remove arg2 = cname
cname = name of custom vector or array to remove
set args = cname v_name subset-ID region-ID
cname = specify as name (no brackets) for custom vector with name
or as name[N] for Nth column of custom array with name
v_name = equal-, particle-, grid-, or surf-style variable with name
subset-ID = mixture ID (particles) or group ID (grid cells or surf elements)
region-ID = only apply to particle/grid/surf in region, NULL to not test
file args = fname M cname1 cname2 ... cnameM
fname = name of file with custom attributes for grid cells or surf elements
M = # of custom values listed on each line of the file
cname1,cname2,...,cnameM = which attribute each line's values are assigned to
cnameI = name of a custom vector
cnameI = name[N] for Nth column of a custom array with name
file/coarse args = Nfile filestyle fname M cname1 cname2 ... cnameM
Nfile = number of coarse files
filestyle = text or binary
fname = name of file with custom attributes for coarse grid cells
M = # of custom values listed for each coarse cell entry in the file
cname1,cname2,...,cnameM = which attribute each coarse cell's values are assigned to
cnameI = name of a custom vector
cnameI = name[N] for Nth column of a custom array with name
Examples:
variable ivec particle id/100000 variable sdvec surf c_1*10+3.5 variable sdarray1 surf s_dvec+1 variable sdarray2 surf v_sdarray1+1
custom particle create ivec int 0 set ivec v_ivec air NULL custom surf create sdvec float 0 set sdvec v_sdvec all NULL custom surf create darray float 2 set darray[1] v_sdarray1 all NULL custom surf set darray[2] v_sdarray2 all NULL custom grid create gvec int 0 create garray float 2 file grid.attributes gvec garray1 garray2 custom particle remove ivec custom surf remove darray
See examples using many of the custom and fix custom command actions in examples/custom
Description:
Create or remove or initialize/reset custom attributes for particles, grid cells, or surface elements.
To create a new attribute, the create action is specified. To remove an attribute, the remove action is specified. The set action evaluates a variable to reset the values for an attribute. The file action reads a file with lines starting with a grid cell ID or surface element ID followed by values for one or more per-grid or per-surf attributes. Particle-style attributes cannot be reset with the file action.
Custom attributes can be vectors (single value per entity) or arrays (mutiple values per entity). They can also be integer or floating point values. See Section 6.17 for an explanation of custom attributes.
The style setting is particle or grid or surf for custom per-particle, per-grid, or per-surf attributes.
The action setting is create or remove or set or file or file/coarse.
The create action creates a new custom attribute called cname and initializes all its values to zero. The datatype is specified as int or float and determines what kind of values the attribute stores. Nc is specified as 0 for custom vector which stores a single value per entity. Specify Nc >= 1 for a custom array which stores Nc values per entity.
The remove action deletes the custom attribute called cname, whether it is a vector or array.
The set and file and file/coarse actions reset the values of custom attribute(s) which must already exist.
The set action resets the values of a custom attribute by evaluating a variable. To operate on a custom vector, cname is simply the name of the vector. To operate on a single column of a custom array, cname is specified as name[N] for the Nth column of a custom array with name.
The specified v_name is the name of the variable which is evaluated. It must be either an equal-style or particle-style or grid-style or surf-style variable. All of these define a mathematical formula which is used to compute the value(s) of the variable. See the variable command for details.
If an equal-style variable is specified, it produces a single value which will be assigned as the custom value to all the particles or grid cells or surface elements (see subset-ID and region-ID discussion below). Otherwise a particle-style variable must be used for style particle, a grid-style variable for style grid, or a surf-style variable for style surf. When it is evaluated it generates one value for each particle, grid cell, or surface element, which is assigned to the custom vector or to a column of the custom array.
Note that the latter 3 variable styles can include outputs from compute or fix commands. They can also include the current timestep (as can equal-style variables) or the spatial position of a particle, grid cell, or surface element in their formula. So it is easy to calculate a value for each entity which varies in time or spatially.
The next two arguments, subset-ID and region-ID, can limit which particles, grid cells, or surface elements are assigned a custom value. An individual particle, grid cell, or surface element must meet both criteria to have its custom value set, otherwise its value is unchanged.
The subset-ID is the ID of a mixture for particles or the ID of a group of grid cells or surface elements. Only particles in the mixture or grid cells/surface elements in the group will be assigned a value. See the mixture and group commands for more details. Note that "all" is a pre-defined mixture ID which contains all particles. Likewise "all" is the name of a pre-defined group with all grid cells or all surface elements.
The region-ID is the ID of a geometric region defined by the region command. Only particles or grid cells or surface elements in the region will have their values set. The center point of a grid cell or surface element is used for the region check. If region-ID is specified as NULL, then the region criterion is not applied.
The file action resets the values of one or more custom attributes by reading them from the fname file. It can only be used with style grid or style surf, not with style particle.
The specified M is the number of cname1,cname2,...,cnameM values that follow and must match the number of values listed on each line in the file, as explained below. A cnameI with no brackets is the name of a custom vector. For a custom array, cnameI must be of the form name[N] for the Nth column of the array.
The format of the file is as follows. Note that the number of grid cells or surf elements specified in the file does not have to equal the total number of grid cells or surface elements. If the ID of a grid cell or surface element does not appear in the file, then its custom attribute value(s) will be unchanged.
The file can start with any number of comment or blank lines. A comment line starts with the "#" character.
The first non-comment, non-blank line has this format:
N Nvalue
N is the count of attribute value lines which follow. These N lines must immediately follow the count line and contain no blank lines. Any remaining lines in the file are ignored. Nvalue is the number of attribute values per line and must equal the specified M.
The format of each attribute value line is as follows:
ID value1 value2 ... valueM
ID is the integer ID of the grid cell or surface element. Note that for hierarchial grids, it must be the integer form of the ID, not the string form (possibly with dashes). M values follow, corresponding to the M argument in the input script, following the fname argument.
The following is an example of a correctly formatted file to set the values for a per-surf custom array with 2 columns. Only the values for 3 surface elements are set.
# custom values for a few surface elements # calculated for test problem XYZ
3 2 1 10.0 5.0 20 12.0 6.5 21 8.0 4.55
This file could be read with an input script command like this:
custom surf create darray float 2 file file.surf 2 darray[1] darray[2]
The file/coarse action resets the values of one or more custom attributes by reading coarse grid values from one or more files. It can only be used with style grid, not with style surf or style particle.
This action is designed to allow input of custom values for some number of "coarse" grid cells. The coarse cells and their values could be output from another code, such as a continuum Navier-Stokes (NS) code or even from an experiment. The coarse cell values are "mapped" to individual SPARTA grid cells, so that per-grid custom attributes for each SPARTA grid cell are set by the values from one of the coarse cells. This is done in the following manner.
Each coarse grid cell is associated with a (cx,cy,cz) point. This could be the center point of grid cell in a NS code which uses finite-volume grid cells. Or it could be a grid point in a NS code which uses finite elements, e.g. the corner point of a triangle (2d) or tetrahedron (3d). Conceptually, the idea is that the small area (2d) or volume (3d) surrounding the point has properties represented by the coarse grid cell values in the file.
All SPARTA grid cells define a center point (sx,sy,sz), which is the center of a rectangle (2d) or parallelepiped (3d).
Both the coarse-grid code and SPARTA should operate on the same simulation domain, which is the simulation box in the case of SPARTA. The set of all (cx,cy,cz) points should "cover" this domain, as do the set of all (sx,sy,sz) points. For each (sx,sz,sz) point, the nearest (cx,cy,cz) point is found. The coarse grid values for that point are assigned to the custom per-grid values of that SPARTA grid cell cell. Here are a few additional details.
IMPORTANT NOTE: The current implementation of this "mapping" operation stores the entire coarse grid on every processor, Each processor then loops over the SPARTA grid cells it own and searches the entire set of of coarse grid point for the nearest, using a k-d tree (in 2 or 3 dimensions). If either the coarse grid storage or tree search becomes a bottleneck for very large-scale problems, we could consider implementing a more parallel algorithm.
Creation of the file(s) read by this action is a pre-processing step. The create_particles command can be used with its custom options to create particles with properties that match the coarse-grid NS values read in and assigned to custom per-grid vectors or arrays by this command. Using this action with the fix custom command could assign per-grid custom values based on different time snapshots from the NS code.
The Nfile argument is the number of files to read. If Nfile > 1, then the specified fname must contain a a wildcard "%" character which is replaced by the numbers from 1 to Nfile to generate each filename. For example, if Nfile = 3 and fname is specified as surf.%.attribute, then files surf.1.attribute, surf.2.attribute, surf.3.attribute, etc will be read. Note that if the fix custom command uses this action, and there are also multiple coarse files for different timesteps, then the specified fname must contain both a wildcard "%" and "*" character.
The reason to use multiple files is that a single file could be extremely large and/or to enable more parallelism by having different processors read different files simultaneously. Conceptually, the information being read is the union of the information from all the individual files. There must be no duplicate coarse grid points (based on point coordinates) in a single or multiple files.
The filestyle argument is text or binary. The format for both kinds of files is explained below. NOTE: The binary format is not yet supported by this command.
The specified (M) number of cname1,cname2,...,cnameM arguments must match the number of values listed on each line in each file. A cnameI with no brackets is the name of a custom vector. For a custom array, cnameI must be of the form cnameI[N] for the Nth column of the array.
For filestyle = text, the format of each file is as follows. It can start with any number of comment or blank lines. A comment line starts with the "#" character. It is a good idea to document in a comment what coarse grid values are listed on each line.
The first non-comment, non-blank line has this format:
N Nvalue
N is the count of coarse cell value lines which follow (in this file). These N lines must immediately follow the count line and contain no blank lines. Any remaining lines in the file are ignored. Nvalue is the number of attribute values per line and must equal the specified M.
The format of each coarse cell value line is as follows:
coarse-ID x y z value1 value2 ... valueM
Coarse-ID is an integer ID of the coarse grid cell. SPARTA ignores this ID, but it may be convenient for indexing the coarse grid cells from another code. Or for indexing the coarse cells across multiple coarse grid files.
The x, y, z values are the coordinates of the coarse grid point associated with the values which follow. Z must be zero for a 2d or axisymmetric simulation.
M values follow, corresponding to the M argument in the input script, following the fname argument.
The following is an example of a correctly formatted file to set the values for a per-grid custom array with 2 columns.
# custom values for a few 2d Navier-Stokes elements # calculated for test problem XYZ # attribute columns = density temperature
4 2 1 5.0 5.0 0.0 10.0 5.0 1 15.0 5.0 0.0 12.0 6.5 1 5.0 15.0 0.0 8.0 4.55 1 15.0 15.0 0.0 9.0 5.5
This file could be read with an input script command like either of these:
custom grid create nrho float 0 create temp float 0 file/coarse 1 text cfile.grid 2 nrho temp custom grid create nrho float 0 create temp float 0 file/coarse 3 text cfile.grid.% 2 nrho temp
The latter command assumes there are 2 other files like this one, with names cfile.grid.1, cfile.grid.2, and cfile.grid.3.
For filestyle = binary, the format of each file is as follows. NOTE: The binary format is not yet supported by this command.
Ncoarse (4-byte integer) Nvalue (4-byte integer) x y z (three 8-byte doubles for 1st coarse cell) Nvalue custom values 1 (Nvalue 8-byte doubles for 1st coarse cell) x y z (three 8-byte doubles for 2nd cell) Nvalue custom values (Nvalue 8-byte doubles for 2nd cell) ... x y z (three 8-byte doubles for Ncoarse cell) Nvaluecustom values (Nvalue 8-byte doubles for Ncoarse cell)
Ncoarse is the number of coarse grid entries in this file. Nvalue is the number of values per coarse grid; it must match the specified M.
X,y,z are the coordinates of the point associated with the values which follow.
Each of the Nvalue values are 8-byte floating point values (doubles). If the corresponding custom attribute in SPARTA is of type int, then the floating point value read from the file will be truncated to an integer. E.g. 12.0 --> 12, 12.3 --> 12.
The coarse grid binary file that corresponds to the coarse grid text file above would store these numbers (without the newlines):
4 2 5.0 5.0 0.0 10.0 5.0 15.0 5.0 0.0 12.0 6.5 5.0 15.0 0.0 8.0 4.55 15.0 15.0 9.0 5.5
This file could be read with an input script command like either of these:
custom grid create nrho float 0 create temp float 0 file/coarse 1 binary cfile.grid 2 nrho temp custom grid create nrho float 0 create temp float 0 file/coarse 3 binary cfile.grid.% 2 nrho temp
The latter command assumes there are 2 other binary files like this one, with names cfile.grid.1, cfile.grid.2, and cfile.grid.3.
Restrictions: none
Related commands:
fix custom, mixture, group, region, create_particles
Default: none