Skip to content

Commit f30747c

Browse files
authored
clarify in a docstring the reasons for not using literal constants within formulae
1 parent bccc803 commit f30747c

File tree

1 file changed

+14
-2
lines changed

1 file changed

+14
-2
lines changed

PySDM/physics/__init__.py

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
11
"""
2-
Physical `PySDM.physics.constants` and simple formulae (essentially one-liners)
2+
Physical constants and formulae (mostly one-liners)
33
that can be automatically either njit-ted or translated to C (in contrast to
4-
more complex code that resides in backends)
4+
more complex code that resides in backends). Note that any code here should
5+
only use constants defined in `PySDM.physics.constants_defaults` and accessible
6+
through the first `const` argument of each formula, for the following reasons:
7+
- it makes it possible for a user to override value of any constant by
8+
passing a `constants` dictionary to the `__init__` of `Formulae`;
9+
- it enforces floating-point cast on all constant values making the code behave
10+
in the same way on both CPU and GPU backends (yes, please use `const.ONE/const.TWO`
11+
instead of `1/2`);
12+
- it enables dimensional analysis logic if the code in question is embedded
13+
in `with DimensionalAnalysis:` block - allows checking physical unit consistency
14+
within unit tests (disable by default, no runtime overhead);
15+
- last but not least, it requires all the constants to be named
16+
(thus resulting in more readable, and more reusable code).
517
"""
618

719
from . import (

0 commit comments

Comments
 (0)