Skip to content

Commit dfe2e03

Browse files
JunCEEEJunCEEE
committed
add MD extension
- add missed scopes, coordinate attribute - correct description of the triclinic simulation box - remove irrelevant simex and lammps references
1 parent b602500 commit dfe2e03

File tree

1 file changed

+132
-0
lines changed

1 file changed

+132
-0
lines changed

‎EXT_MD.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
Domain-Specific Naming Conventions for Molecular Dynamics Simulation Codes
2+
=======================================================================
3+
4+
openPMD extension name: `MD`
5+
6+
VERSION: 0.0.3 (January 26th, 2020)
7+
8+
Introduction
9+
------------
10+
11+
This extension is specifically designed for the molecular dynamics simulation codes.
12+
13+
The current version of this extension is suitable to allow the output of
14+
arbitrary simulation codes to be post-processed and compared with common
15+
tools and frameworks. Future versions will define a common set of required
16+
records and further attributes.
17+
18+
The example data structure can be found [HERE](https://github.com/ejcjason/MDDomainExtension).
19+
20+
Root Group
21+
---------------------------
22+
23+
### Additional Attributes for the `Root` group
24+
25+
The following additional attributes are defined in this extension.
26+
The individual requirement is given in `scope`.
27+
28+
- `forceField`
29+
- type: 1-dimensional array of N (string) elements, where N is the number of force fields (interatomic potentials) implemented in the simulation.
30+
- scope: *optional*
31+
- description: the methods implemented in the simulation to describe the force fields (interatomic potentials). See [Interatomic Potentials Repository](https://www.ctcms.nist.gov/potentials/).
32+
- example values:
33+
- `eam/alloy`
34+
- `lj/cut 3.0`
35+
- ...
36+
- `forceFieldParameters`
37+
- type: 1-dimensional array of N (string) elements, where N is the number of force fields (interatomic potentials) implemented in the simulation.
38+
- scope: *optional*
39+
- description: the parameters specification for the `forceField` methods. See [Interatomic Potentials Repository](https://www.ctcms.nist.gov/potentials/).
40+
- example values:
41+
- `pair_coeff * * 1 1`
42+
- `pair_coeff 1 1 Cu_mishin1.eam.alloy Cu`
43+
- ...
44+
45+
Observable Records
46+
---------------------------
47+
48+
`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).
49+
50+
### Naming conventions
51+
52+
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).
53+
54+
- `scalar` record
55+
- type: *(any type)*
56+
- data set: `recordName` unique name in group `basePath` + `observables`
57+
- examples:
58+
- /data/observables/temperature
59+
- /data/observables/pressure
60+
61+
### Attributes for each `observable` record
62+
63+
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).
64+
65+
66+
Particle Records
67+
---------------------------
68+
69+
### Additional attributes for each `position` record
70+
71+
The following attributes are defined in this extension. The individual requirement is given in `scope`.
72+
73+
- `coordinate`
74+
- type: *(string)*
75+
- scope: *required*
76+
- description: the representation of the stored position coordinates
77+
- available values:
78+
- `absolute` the unscaled coordinates
79+
- `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`
80+
81+
### Additional Sub-Group for each Particle Species
82+
83+
`box` is an *optional* sub-group for each particle species to contain the information of the simulation box.
84+
85+
### Attributes for Sub-Group `box`
86+
87+
The following attributes are defined in this extension.
88+
If the `box` sub-group exists, the following attributes within it are required.
89+
The individual requirement is given in `scope`.
90+
91+
- `dimension`
92+
- type: *(uint32)*
93+
- scope: *required*, if `box` sub-group exists
94+
- description: the spacial dimension **D** of the simulation box.
95+
- example values:
96+
- `2` 2D simulation box
97+
- `3` 3D simulation box
98+
- ...
99+
100+
- `boundary`
101+
- type: array of *(string)* containing **D** elements, where **D** is the value of `dimension`.
102+
- scope: *required*, if `box` sub-group exists
103+
- description: the boundary condition of the box along each dimension. The allowed values in `boundary` are either **periodic** or **none**.
104+
- example values:
105+
- `["periodic","periodic","periodic"]` periodic in all the three dimensions
106+
- `["none","periodic","periodic"]` periodic in only *y* and *z* dimensions
107+
108+
### Records for Sub-Group `box`
109+
110+
The following records are defined in this extension.
111+
If the `box` sub-group exists, the following records within it are required.
112+
The individual requirement is given in `scope`.
113+
- `edge`
114+
- type: DxD array of *(floatX)*, where **D** is the value of `dimension`.
115+
- scope: *required*, if `box` sub-group exists
116+
- description: the edge vector of the simulation box in each dimension.
117+
- example values:
118+
- `[[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.)
119+
- `[[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.)
120+
- `[[1.,0.],[1.,1.]]` 2D rectangle simulation box, Ax = (1.,0.), Ay = (0.,1.)
121+
- `limit`
122+
- type: Dx2 array of *(floatX)*, where **D** is the value of `dimension`.
123+
- scope: *required*, if `box` sub-group exists
124+
- description: the starting and the ending of each edge vector.
125+
- example values:
126+
- `[[0.,300.],[0.,150.],[0.,180.]]` A 3D box example: xlo = 0, xhi = 300, ylo = 0, yhi = 150, zlo = 0, zhi = 180
127+
- `[[0.,300.],[15.,280.]]` A 2D box example: xlo = 0, xhi = 300, ylo = 15, yhi = 280
128+
- `unitSI`
129+
- type: *(float64)*
130+
- scope: *required*, if `box` sub-group exists
131+
- description: unit-conversion factor to convert simulation unit to SI units
132+
- example: `1.0e-10`

0 commit comments

Comments
 (0)