# `spex`: Technical README

### Conventions

- Init parameters (aka "hypers") should always be passed as bare python types: `int`, `float`, `list`, `dict` or `tuple`, so we can cleanly serialise them to `.yaml` without too much of a fuss
- `max_X` indicates the maximum value taken by `X`, starting from `0`. Therefore, `X` has `max_X + 1` values, from `0` to `max_X`. For example, `max_angular=3` indicates that spherical harmonics are enumerated from `l=0` to `l=3`. Note that this is in contrast to `rascaline`, where `max_radial` is exclusive and `max_angular` is inclusive.
- `X_per_Y` indicates the number of values `X` can take in channels of `Y`. For example, if there are `3` basis functions for `l=0` and `4` for `l=1`, this means `n_per_l=[3, 4]`. In `spex` we usually simply return lists of tensors for this job, rather than packing everything into a dense tensor. In benchmarks, we find that this is actually faster for large systems and large bases, and only slightly slower for the small case.
- Since `torch` does not yet fully support `jaxtyping`-style shape annotations, we make do with comments that indicate the expected shapes of inputs/intermediate results. The notation looks like this: `[pair, l]` indicates that we have a tensor with two dimensions, named `pair` and `l`, the spherical harmonic order. We also write things like `[pair, l=1 m=-1 l=1 m=0 ...]` to suggest that all features for one `l` and increasing `m` are found in a 2D tensor, stacked along the `-1` dimension. We further use `[[pair, l=0 m=0], [pair, l=1 m=-1 ...]]` to suggest a list of tensors where each share a dimension `pair` and the rest is stacked spherical features of different `l` with increasing `m`. `[[pair, l=0 m], [pair, l=1 m], ...]` is a more compact version to write this.
- Only things in `__all__` are considered public API, and only these are expected to be documented via docstrings. Similarly, only items mentioned in a docstring as attribute can be considered as public API, everything else should not be relied upon.
- Type annotations are not used, unless absolutely required by torchscript.
