Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update significantly outdated documentation of global constants #789

Merged
merged 2 commits into from
Aug 2, 2024
Merged

Update significantly outdated documentation of global constants #789

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
24035d7
update GLOBALS.md
thehrh Aug 1, 2024
df6e11b
C_FTYPE string adapted for single-precision and cosmetics
thehrh Aug 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 59 additions & 41 deletions pisa/stages/GLOBALS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,63 +3,81 @@
Global variables and constants are defined upon initialization of the `pisa` package (`pisa/__init__.py`) and are available to all of its modules.
They can be imported via `from pisa import <constant>`.

Here we keep track of which global constants are available, what their purpose is, and by which stage(s) they are used.
Here we keep track of which global constants are available, what their purpose is, and by which stages they are used.

## Description

| Constant | Description | Default | Overwritten by environment variables (priority indicated where necessary) |
| ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `NUMBA_CUDA_AVAIL` | Availability of Numba's CUDA interface | `False` (unless installed and CUDA-capable GPU available) | |
| `TARGET` | Numba compilation target | `gpu` if `NUMBA_CUDA_AVAIL`, `None` otherwise | `PISA_TARGET` |
| `NUMBA_CUDA_AVAIL` | Availability of Numba's CUDA interface | `False` (unless CUDA-capable GPU available) | |
| `TARGET` | Numba compilation target | `cpu` | `PISA_TARGET` (GPU target only possible if `NUMBA_CUDA_AVAIL`) |
| `OMP_NUM_THREADS` | Number of threads allocated to OpenMP | `1` | `OMP_NUM_THREADS` |
| `FTYPE` | Global floating point data type | `np.float64` | `PISA_FTYPE` |
| `PISA_NUM_THREADS` | Global limit for number of threads (also upper limit for `OMP_NUM_THREADS`) | `1` (`numba.config.NUMBA_NUM_THREADS`) for `TARGET='cpu'` (`'parallel'`) | `PISA_NUM_THREADS` |
| `FTYPE` | Global floating-point data type | `np.float64` | `PISA_FTYPE` |
| `CTYPE` | Global complex-valued floating-point data type | `np.complex128` (`np.complex64`) for `FTYPE=np.float64(32)` | |
| `ITYPE` | Global integer data type | `np.int64` (`np.int32`) for `FTYPE=np.float64(32)` | |
| `HASH_SIGFIGS` | Number of significant digits used for hashing numbers, depends on `FTYPE` | `12(5)` for `FTYPE=np.float64(32)` | |
| `EPSILON` | Best numerical precision, derived from `HASH_SIGFIGS` | `10**(-HASH_SIGFIGS)` | |
| `C_FTYPE` | C floating point type corresponding to `FTYPE` | `'double'('single')` for `FTYPE=np.float64(32)` | |
| `C_PRECISION_DEF` | C precision of floating point calculations, derived from `FTYPE` | `'DOUBLE_PRECISION'('SINGLE_PRECISION')` for `FTYPE=np.float64(32)` | |
| `C_FTYPE` | C floating-point type corresponding to `FTYPE` | `'double'` (`'float'`) for `FTYPE=np.float64(32)` | |
| `C_PRECISION_DEF` | C precision of floating-point calculations, derived from `FTYPE` | `'DOUBLE_PRECISION'` (`'SINGLE_PRECISION'`) for `FTYPE=np.float64(32)` | |
| `CACHE_DIR` | Root directory for storing PISA cache files | `'~/.cache/pisa'` | 1.`PISA_CACHE_DIR`, 2.`XDG_CACHE_HOME/pisa` |

## Usage
The table below depicts which services make use of a select set of global constants.
Note that the table entries are derived from both the module files themselves (where the services are defined) but also from any `pisa.utils` objects they make use of.
Note that the table entries are derived both from the module files themselves (where the services are defined) and from any `pisa.utils` objects they make use of (in particular, reliance on "PISA-tailored" jit in `numba_tools`).
Constants which are implicitly used by all services via `pisa.core` objects (e.g. `HASH_SIGFIGS`, `CACHE_DIR`) are not shown.
Also note that where a service implements `FTYPE` and relies on C extension code, the simultaneous implementation of `C_FTYPE` and `C_PRECISION_DEF` is implied.

**Legend**
- :heavy_check_mark:: implements
- :black_square_button:: does not implement but does not fail (i.e., ignores)
- :heavy_exclamation_mark:: implements and fails if `False` (i.e., depends)
- :heavy_minus_sign:: does not implement but does not fail (i.e., ignores)

| | `NUMBA_CUDA_AVAIL` | `OMP_NUM_THREADS` | `FTYPE` |
| | `TARGET` | `PISA_NUM_THREADS` | `FTYPE` |
| :------------------------: | :-------------------: | :-------------------: | :-------------------: |
| `aeff.hist` | :black_square_button: | :black_square_button: | :black_square_button: |
| `aeff.param` | :black_square_button: | :black_square_button: | :black_square_button: |
| `aeff.aeff` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark: |
| `aeff.smooth` | :black_square_button: | :black_square_button: | :black_square_button: |
| `combine.nutau` | :black_square_button: | :black_square_button: | :black_square_button: |
| `data.data` | :black_square_button: | :black_square_button: | :black_square_button: |
| `data.events_to_data` | :black_square_button: | :black_square_button: | :black_square_button: |
| `data.icc` | :black_square_button: | :black_square_button: | :black_square_button: |
| `data.sample` | :black_square_button: | :black_square_button: | :black_square_button: |
| `data.simple_data_loader` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark: |
| `data.toy_event_generator` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark: |
| `discr_sys.fit` | :black_square_button: | :black_square_button: | :black_square_button: |
| `discr_sys.hyperplane` | :black_square_button: | :black_square_button: | :black_square_button: |
| `discr_sys.hyperplanes` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark: |
| `discr_sys.polyfits` | :black_square_button: | :black_square_button: | :black_square_button: |
| `flux.dummy` | :black_square_button: | :black_square_button: | :black_square_button: |
| `flux.honda` | :black_square_button: | :black_square_button: | :black_square_button: |
| `flux.mceq` | :black_square_button: | :black_square_button: | :black_square_button: |
| `flux.barr_simple` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark: |
| `osc.prob3` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark: |
| `pid.hist` | :black_square_button: | :black_square_button: | :black_square_button: |
| `pid.param` | :black_square_button: | :black_square_button: | :black_square_button: |
| `pid.smooth` | :black_square_button: | :black_square_button: | :black_square_button: |
| `reco.hist` | :black_square_button: | :black_square_button: | :black_square_button: |
| `reco.hist` | :black_square_button: | :black_square_button: | :black_square_button: |
| `reco.param` | :black_square_button: | :black_square_button: | :black_square_button: |
| `reco.vbwkde` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `unfold.roounfold` | :black_square_button: | :black_square_button: | :black_square_button: |
| `utils.hist` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark : |
| `xsec.genie` | :black_square_button: | :black_square_button: | :black_square_button: |
| `xsec.genie_sys` | :heavy_check_mark: | :black_square_button: | :heavy_check_mark: |
| `absorption.earth_absorption` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `aeff.aeff` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `aeff.weight` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `aeff.weight_hnl` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `background.atm_muons` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `data.csv_data_hist` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.csv_icc_hist` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.csv_loader` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.freedom_hdf5_loader` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.grid` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.licloader_weighter` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.meows_loader` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.simple_data_loader` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.simple_signal` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.sqlite_loader` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `data.toy_event_generator` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `discr_sys.hypersurfaces` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `discr_sys.ultrasurfaces` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `flux.airs` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `flux.astrophysical` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `flux.barr_simple` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `flux.daemon_flux` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `flux.hillasg` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `flux.honda_ip` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `flux.mceq_barr` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `flux.mceq_barr_red` | :heavy_check_mark: | :heavy_minus_sign: | :heavy_check_mark: |
| `likelihood.generalized_llh_params` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `osc.decoherence` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `osc.globes` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `osc.nusquids` | :heavy_minus_sign: | :heavy_check_mark: | :heavy_check_mark: |
| `osc.prob3` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `osc.two_nu_osc` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `pid.shift_scale_pid` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `reco.resolutions` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `reco.simple_param` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `utils.add_indices` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `utils.adhoc_sys` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `utils.bootstrap` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `utils.fix_error` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `utils.hist` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `utils.kde` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `utils.kfold` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: |
| `utils.resample` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `utils.set_variance` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `xsec.dis_sys` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `xsec.genie_sys` | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: |
| `xsec.nutau_xsec` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
Loading