-
Notifications
You must be signed in to change notification settings - Fork 29
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- add missed scopes, coordinate attribute - correct description of the triclinic simulation box - remove irrelevant simex and lammps references
- Loading branch information
Showing
1 changed file
with
132 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,132 @@ | ||
Domain-Specific Naming Conventions for Molecular Dynamics Simulation Codes | ||
======================================================================= | ||
|
||
openPMD extension name: `MD` | ||
|
||
VERSION: 0.0.3 (January 26th, 2020) | ||
|
||
Introduction | ||
------------ | ||
|
||
This extension is specifically designed for the molecular dynamics simulation codes. | ||
|
||
The current version of this extension is suitable to allow the output of | ||
arbitrary simulation codes to be post-processed and compared with common | ||
tools and frameworks. Future versions will define a common set of required | ||
records and further attributes. | ||
|
||
The example data structure can be found [HERE](https://github.com/ejcjason/MDDomainExtension). | ||
|
||
Root Group | ||
--------------------------- | ||
|
||
### Additional Attributes for the `Root` group | ||
|
||
The following additional attributes are defined in this extension. | ||
The individual requirement is given in `scope`. | ||
|
||
- `forceField` | ||
- type: 1-dimensional array of N (string) elements, where N is the number of force fields (interatomic potentials) implemented in the simulation. | ||
- scope: *optional* | ||
- description: the methods implemented in the simulation to describe the force fields (interatomic potentials). See [Interatomic Potentials Repository](https://www.ctcms.nist.gov/potentials/). | ||
- example values: | ||
- `eam/alloy` | ||
- `lj/cut 3.0` | ||
- ... | ||
- `forceFieldParameters` | ||
- type: 1-dimensional array of N (string) elements, where N is the number of force fields (interatomic potentials) implemented in the simulation. | ||
- scope: *optional* | ||
- description: the parameters specification for the `forceField` methods. See [Interatomic Potentials Repository](https://www.ctcms.nist.gov/potentials/). | ||
- example values: | ||
- `pair_coeff * * 1 1` | ||
- `pair_coeff 1 1 Cu_mishin1.eam.alloy Cu` | ||
- ... | ||
|
||
Observable Records | ||
--------------------------- | ||
|
||
`observables` is an *optional* group that contains physical observables that are derived from the system state, i.e., thermodynamic information (e.g. temperature, energy, pressure). | ||
|
||
### Naming conventions | ||
|
||
The naming conventions conforming the naming conventions for [Scalar, Vector and Tensor Records](https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md#naming-conventions) in [openPMD base standard](https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md). | ||
|
||
- `scalar` record | ||
- type: *(any type)* | ||
- data set: `recordName` unique name in group `basePath` + `observables` | ||
- examples: | ||
- /data/observables/temperature | ||
- /data/observables/pressure | ||
|
||
### Attributes for each `observable` record | ||
|
||
The attributes of unit system for records should be included as defined in [openPMD base standard](https://github.com/openPMD/openPMD-standard/blob/latest/STANDARD.md#unit-systems-and-dimensionality). | ||
|
||
|
||
Particle Records | ||
--------------------------- | ||
|
||
### Additional attributes for each `position` record | ||
|
||
The following attributes are defined in this extension. The individual requirement is given in `scope`. | ||
|
||
- `coordinate` | ||
- type: *(string)* | ||
- scope: *required* | ||
- description: the representation of the stored position coordinates | ||
- available values: | ||
- `absolute` the unscaled coordinates | ||
- `fractional` the coordinates that are scaled in the range of [0,1] relative to the length of each box edge; in this coordinate system, the `unitSI` of each position component should be `1.0` | ||
|
||
### Additional Sub-Group for each Particle Species | ||
|
||
`box` is an *optional* sub-group for each particle species to contain the information of the simulation box. | ||
|
||
### Attributes for Sub-Group `box` | ||
|
||
The following attributes are defined in this extension. | ||
If the `box` sub-group exists, the following attributes within it are required. | ||
The individual requirement is given in `scope`. | ||
|
||
- `dimension` | ||
- type: *(uint32)* | ||
- scope: *required*, if `box` sub-group exists | ||
- description: the spacial dimension **D** of the simulation box. | ||
- example values: | ||
- `2` 2D simulation box | ||
- `3` 3D simulation box | ||
- ... | ||
|
||
- `boundary` | ||
- type: array of *(string)* containing **D** elements, where **D** is the value of `dimension`. | ||
- scope: *required*, if `box` sub-group exists | ||
- description: the boundary condition of the box along each dimension. The allowed values in `boundary` are either **periodic** or **none**. | ||
- example values: | ||
- `["periodic","periodic","periodic"]` periodic in all the three dimensions | ||
- `["none","periodic","periodic"]` periodic in only *y* and *z* dimensions | ||
|
||
### Records for Sub-Group `box` | ||
|
||
The following records are defined in this extension. | ||
If the `box` sub-group exists, the following records within it are required. | ||
The individual requirement is given in `scope`. | ||
- `edge` | ||
- type: DxD array of *(floatX)*, where **D** is the value of `dimension`. | ||
- scope: *required*, if `box` sub-group exists | ||
- description: the edge vector of the simulation box in each dimension. | ||
- example values: | ||
- `[[1.,0.,0.],[0.,1.,0.],[0.,0.,1.]]` 3D cubic simulation box, Ax = (1.,0.,0.), Ay = (0.,1.,0.), Az = (0.,0.,1.) | ||
- `[[3.46,0.,0.],[1.73,2.997,0.],[0.,0.,10.]]` 3D triclinic simulation box, Ax = (3.46,0.,0.), Ay = (1.73,2.997,0.), Az = (0.,0.,10.) | ||
- `[[1.,0.],[1.,1.]]` 2D rectangle simulation box, Ax = (1.,0.), Ay = (0.,1.) | ||
- `limit` | ||
- type: Dx2 array of *(floatX)*, where **D** is the value of `dimension`. | ||
- scope: *required*, if `box` sub-group exists | ||
- description: the starting and the ending of each edge vector. | ||
- example values: | ||
- `[[0.,300.],[0.,150.],[0.,180.]]` A 3D box example: xlo = 0, xhi = 300, ylo = 0, yhi = 150, zlo = 0, zhi = 180 | ||
- `[[0.,300.],[15.,280.]]` A 2D box example: xlo = 0, xhi = 300, ylo = 15, yhi = 280 | ||
- `unitSI` | ||
- type: *(float64)* | ||
- scope: *required*, if `box` sub-group exists | ||
- description: unit-conversion factor to convert simulation unit to SI units | ||
- example: `1.0e-10` |