Skip to content

Commit

Permalink
clarify in a docstring the reasons for not using literal constants wi…
Browse files Browse the repository at this point in the history
…thin formulae
  • Loading branch information
slayoo authored Feb 12, 2024
1 parent bccc803 commit f30747c
Showing 1 changed file with 14 additions and 2 deletions.
16 changes: 14 additions & 2 deletions PySDM/physics/__init__.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,19 @@
"""
Physical `PySDM.physics.constants` and simple formulae (essentially one-liners)
Physical constants and formulae (mostly one-liners)
that can be automatically either njit-ted or translated to C (in contrast to
more complex code that resides in backends)
more complex code that resides in backends). Note that any code here should
only use constants defined in `PySDM.physics.constants_defaults` and accessible
through the first `const` argument of each formula, for the following reasons:
- it makes it possible for a user to override value of any constant by
passing a `constants` dictionary to the `__init__` of `Formulae`;
- it enforces floating-point cast on all constant values making the code behave
in the same way on both CPU and GPU backends (yes, please use `const.ONE/const.TWO`
instead of `1/2`);
- it enables dimensional analysis logic if the code in question is embedded
in `with DimensionalAnalysis:` block - allows checking physical unit consistency
within unit tests (disable by default, no runtime overhead);
- last but not least, it requires all the constants to be named
(thus resulting in more readable, and more reusable code).
"""

from . import (
Expand Down

0 comments on commit f30747c

Please sign in to comment.