Skip to content

Commit 79d5b60

Browse files
scytackiscytacki
committed
split out constants and units from readme
1 parent ebb8adf commit 79d5b60

File tree

2 files changed

+85
-82
lines changed

2 files changed

+85
-82
lines changed

‎developer-doc/physical-constants-and-units.md

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Physical constants and units
2+
3+
The core of the molecular dynamics engine performs computations using dimensioned quantities; we do
4+
not nondimensionalize to reduced units. The units used internally are:
5+
6+
- femtoseconds
7+
- nanometers
8+
- Dalton (atomic mass units)
9+
- elementary charges
10+
- Kelvin
11+
12+
(Note that we will shortly switch to representing time in picoseconds rather than femtoseconds.)
13+
14+
The above implies that the 'natural' unit of energy within the application is the "Dalton nm^2 /
15+
fs^2", and the natural unit of force is the "Dalton nm / fs^2". We call these "MW Energy Units" and
16+
"MW Force Units" respectively; however, externally-facing methods accept and report energies in
17+
electron volts, rather than "MW Units".
18+
19+
The molecular dynamics engine in `src/md-engine` contains a submodule, defined in `src/md-
20+
engine/constants/` which defines physical useful constants and allows one to perform some unit
21+
conversions in a mnemonic way.
22+
23+
Once you have `require()`d the constants module appropriately, you can access the constants, 2
24+
converter methods, and an object that defines the various units. For the following, assume the
25+
`constants` module has been `require()`d into the variable `constants`.
26+
27+
## Units
28+
29+
The various units are available as properties of the object `constants.unit`, and are named
30+
appropriately. The units themselves are objects, but their properties are not external API; rather,
31+
the unit objects are expected to be passed as arguments to conversion methods which return numeric
32+
values. Units are named in the singular and are written as all-uppercase (they are constants).
33+
34+
Some example units are:
35+
36+
- `constants.unit.JOULE` constants.unit.MW_ENERGY_UNIT` (Dalton nm^2 / fs^2, see above)
37+
- `constants.unit.METERS_PER_FARAD`
38+
39+
## Physical Constants
40+
41+
The various constants are defined as properties of the `constants` object. However, these do not
42+
have numerical values; instead, they each contain a single method, `as`, which accepts a unit (see
43+
above) and returns the numerical value of that constant in terms of that unit. This is intended to
44+
be a convenience for the programmer and to reduce the likelihood that he or she will forget to keep
45+
track of the units in which a value is stored.
46+
47+
For example,
48+
49+
- `constants.BOLTZMANN_CONSTANT.as(constants.unit.JOULES_PER_KELVIN)` (== 1.380658e-23)
50+
- `constants.PERMITTIVITY_OF_FREE_SPACE.as(constants.unit.FARADS_PER_METER)` (== 8.854187e-12)
51+
52+
## Unit conversions
53+
54+
The `constants` module does not attempt to do dimensional analysis (for example, converting kg m/s^2
55+
into Newtons). However, it can convert a value between two different units that measure the same
56+
type of quantity, and it can supply conversion ratios that make it easier to do dimensional analysis
57+
carefully in your own code.
58+
59+
60+
### Converting a value between two unit types:
61+
62+
To convert the value 1kg into Daltons (aka atomic mass units), use the `convert` method:
63+
64+
`constants.convert(1, { from: constants.unit.KILOGRAM, to: constants.unit.DALTON })` (==
65+
6.022137376997844e+26)
66+
67+
### Finding the ratio between two unit types and rolling your own unit conversions:
68+
69+
To find the number of atomic masses in 1 kg, use the `ratio` method with the `per` argument:
70+
71+
`constants.ratio(constants.unit.DALTON, { per: constants.unit.KILOGRAM })`
72+
(== 6.022137376997844e+26)
73+
74+
This form of ratio is especially useful for unit conversion, and the "per" is intended as a
75+
mnemonic. The number reported above, for example, is easily understood to be "6.022 x 10^26 Dalton
76+
per kilogram" and can therefore be used as a factor that "cancels" kilograms and replaces them with
77+
Daltons in a compound unit such as "kg m/s".
78+
79+
However, sometimes you want the value of a Dalton expressed as kilograms. Although you *could*
80+
reverse the units in the above function call, or divide 1 by the result above, it is better to use
81+
the mnemonic `as` form of `ratio`:
82+
83+
`constants.ratio(constants.unit.DALTON, { as: constants.unit.KILOGRAM })` (== 1.66054e-27)

‎readme.md

+2-82
Original file line numberDiff line numberDiff line change
@@ -1055,89 +1055,9 @@ Start node-inspector:
10551055
info - socket.io started
10561056
visit http://0.0.0.0:8080/debug?port=5858 to start debugging
10571057

1058-
## Physical constants and units
1058+
## Physical Constants and Units
10591059

1060-
The core of the molecular dynamics engine performs computations using dimensioned quantities; we do
1061-
not nondimensionalize to reduced units. The units used internally are:
1062-
1063-
- femtoseconds
1064-
- nanometers
1065-
- Dalton (atomic mass units)
1066-
- elementary charges
1067-
- Kelvin
1068-
1069-
(Note that we will shortly switch to representing time in picoseconds rather than femtoseconds.)
1070-
1071-
The above implies that the 'natural' unit of energy within the application is the "Dalton nm^2 /
1072-
fs^2", and the natural unit of force is the "Dalton nm / fs^2". We call these "MW Energy Units" and
1073-
"MW Force Units" respectively; however, externally-facing methods accept and report energies in
1074-
electron volts, rather than "MW Units".
1075-
1076-
The molecular dynamics engine in `src/md-engine` contains a submodule, defined in `src/md-
1077-
engine/constants/` which defines physical useful constants and allows one to perform some unit
1078-
conversions in a mnemonic way.
1079-
1080-
Once you have `require()`d the constants module appropriately, you can access the constants, 2
1081-
converter methods, and an object that defines the various units. For the following, assume the
1082-
`constants` module has been `require()`d into the variable `constants`.
1083-
1084-
### Units
1085-
1086-
The various units are available as properties of the object `constants.unit`, and are named
1087-
appropriately. The units themselves are objects, but their properties are not external API; rather,
1088-
the unit objects are expected to be passed as arguments to conversion methods which return numeric
1089-
values. Units are named in the singular and are written as all-uppercase (they are constants).
1090-
1091-
Some example units are:
1092-
1093-
- `constants.unit.JOULE` constants.unit.MW_ENERGY_UNIT` (Dalton nm^2 / fs^2, see above)
1094-
- `constants.unit.METERS_PER_FARAD`
1095-
1096-
### Physical Constants
1097-
1098-
The various constants are defined as properties of the `constants` object. However, these do not
1099-
have numerical values; instead, they each contain a single method, `as`, which accepts a unit (see
1100-
above) and returns the numerical value of that constant in terms of that unit. This is intended to
1101-
be a convenience for the programmer and to reduce the likelihood that he or she will forget to keep
1102-
track of the units in which a value is stored.
1103-
1104-
For example,
1105-
1106-
- `constants.BOLTZMANN_CONSTANT.as(constants.unit.JOULES_PER_KELVIN)` (== 1.380658e-23)
1107-
- `constants.PERMITTIVITY_OF_FREE_SPACE.as(constants.unit.FARADS_PER_METER)` (== 8.854187e-12)
1108-
1109-
### Unit conversions
1110-
1111-
The `constants` module does not attempt to do dimensional analysis (for example, converting kg m/s^2
1112-
into Newtons). However, it can convert a value between two different units that measure the same
1113-
type of quantity, and it can supply conversion ratios that make it easier to do dimensional analysis
1114-
carefully in your own code.
1115-
1116-
1117-
#### Converting a value between two unit types:
1118-
1119-
To convert the value 1kg into Daltons (aka atomic mass units), use the `convert` method:
1120-
1121-
`constants.convert(1, { from: constants.unit.KILOGRAM, to: constants.unit.DALTON })` (==
1122-
6.022137376997844e+26)
1123-
1124-
#### Finding the ratio between two unit types and rolling your own unit conversions:
1125-
1126-
To find the number of atomic masses in 1 kg, use the `ratio` method with the `per` argument:
1127-
1128-
`constants.ratio(constants.unit.DALTON, { per: constants.unit.KILOGRAM })`
1129-
(== 6.022137376997844e+26)
1130-
1131-
This form of ratio is especially useful for unit conversion, and the "per" is intended as a
1132-
mnemonic. The number reported above, for example, is easily understood to be "6.022 x 10^26 Dalton
1133-
per kilogram" and can therefore be used as a factor that "cancels" kilograms and replaces them with
1134-
Daltons in a compound unit such as "kg m/s".
1135-
1136-
However, sometimes you want the value of a Dalton expressed as kilograms. Although you *could*
1137-
reverse the units in the above function call, or divide 1 by the result above, it is better to use
1138-
the mnemonic `as` form of `ratio`:
1139-
1140-
`constants.ratio(constants.unit.DALTON, { as: constants.unit.KILOGRAM })` (== 1.66054e-27)
1060+
[Physical Constants and Units](developer-doc/physical-constants-and-units.md)
11411061

11421062
## Deployment
11431063

0 commit comments

Comments
 (0)