Metadata-Version: 2.4
Name: config-spectrum
Version: 0.2.0
Summary: Configuration for the SPECTRUM software suite, enabling C++-native, compile-time full codebase parameterization.
Author-email: Vladimir Florinski <vaf0001@uah.edu>, Juan Alonso Guzmán <jgg008@uah.edu>, Lucius Schoenbaum <lts0016@uah.edu>
License: MIT
Requires-Python: >=3.9
Requires-Dist: tomli>=2.0.2; python_version < '3.11'
Description-Content-Type: text/markdown



# Config-SPECTRUM

![Development Status](https://img.shields.io/badge/status-experimental-orange)

> ⚠️ **DISCLAIMER:** This project is currently under active pre-alpha development.

Config-SPECTRUM is a configuration assistant for [SPECTRUM](https://github.com/vflorins/SPECTRUM), facilitating C++-native compile-time configuration and parameter management. 

## Quick Start 🥚

The script is accessed via a command line entry point ``config-spectrum``. 
Compile-time constants (parameters) may be set at the command line. 
The tool will also resolve a set of contingent defaults. 

For example:
```bash
config-spectrum . -b Dipole -t Lorentz -d None
```
This will generate a config file with a default name (``config.hh``) in the current directory (``.``). 
This file will inject the default values for a Lorentz particle trajectory in a Dipole background, 
with no Diffusion model applied. The path argument is usually (``.``), but it can be modified. 
To change the name of the file, use the ``-o`` flag. As in:
```bash
config-spectrum ./my_path -b Dipole -t Lorentz -d None -o my_first_test
```
Now the generated file is in a local subdirectory, and is named ``my_first_test.config.hh``. 
Config files are C++ header files. By convention, suffixed with ``config.hh`` instead of the 
usual ``.hh`` for a C++ header file. 

For more information, use the help flag ``config-spectrum -h`` or ``config-spectrum --help``.


## Guide for Developers 💾

Except for the frontend in ``main.py``, the implementation is in the 
submodule ``_impl``, and should not need to be frequently modified.

The files ``config_parameters.py`` and ``config_physical.py`` in ``config-spectrum``, 
and the file ``common/compiletime_lists.hh`` are 
the "source of truth" for all of SPECTRUM. 

* ``compiletime_lists.hh``. This file and included header files determine 
fundamental structure is exposed at compile-time. In particular, it determines what Backgrounds, 
Trajectories, and Diffusion classes are recognized by ``config-spectrum``. 
The enum classes there may be edited when the source code is changed, 
to reflect changes to the SPECTRUM object model. For example, 
a new Background implemented in ``background_silly.hh`` / ``background_silly.cc``
can be registered in ``compiletime_lists.hh`` by adding ``Silly`` to the 
list of backgrounds.

* ``config_parameters.py``. Contains a specification of all (hyper)parameters
for the SPECTRUM test particle trajectory solver. 
It provides type information, possible ranges,
a docstring, and a globally-defined fallthrough default value. 
**Modifications of this file should be made in tandem with review and 
possible modifications of ``compiletime_lists.hh``.**

* ``config_physical.py``. Contains 

This leads to the following general heuristic for developers:
* **Modifications of ``compiletime_lists.hh`` should be made in tandem with review and
  possible modifications of ``config_parameters.py``, and vice versa.**
* **Modifications of ``config_physical.py`` can be freely made.**

Whenever changes to either of the ``.py`` files are made, 
the ``.config.hh`` files that appear in ``/src/`` need to be updated. 
This process has been automated. You only need to run:
```bash
config-spectrum . --mkdefaults
```
To proceed cautiously, it is recommended to run this first in testing mode:
```bash
config-spectrum . --mkdefaults --test
```

## Setting default values in ``config_physical.py``

The dict of dicts in ``conig_physical.py`` defines a "reasonable" default
for the particular trajectory/background/diffusion type. 
This file is the unique location in the code where
these default values are defined.

There is no inheritance mechanism, so
each class repeats parameters defined in base classes.
In some cases, this is indicated by commented-out dividers. 

The dicts are used on an "as-needed" basis, so the definitions here 
are not brittle. ``config-spectrum`` will automatically check that 
every case has a default value. 

The formatting of values of key-value pairs 
is performed by the ``value`` method in ``_impl/configdata.py``. 
Each parameter (say, a floating point parameter) has its type resolved 
via the dictionaries in ``config.parameters.py``. If this type is ``float``, 
then the value is set as a float. If this type is ``string`` (for example,
a file name), then this value is set as a string. Default values of strings can 
be set using an ordinary double-quote "..." string.
If the type is type (a C++ type), then the type is set here
inside of a double-quote string. Brace-initializer expressions can be 
used for default values. 

The dict of dicts ``physical_defaults`` has the following structure:
```
physical_defaults = {
    'Background': ..., # dict of backgrounds
    'Trajectory': ..., # dict of trajectories
    'Diffusion': ..., # dict of diffusions
}
```

## Notes

* It is not possible to do what `config-spectrum` does using compile-time language features of C++20,
the version used by SPECTRUM. Therefore a custom-built solution is needed,
and this is one possibility (among many) which takes advantage of the well-developed
Python ecosystem. Experience with `config-spectrum`




### Last Updated

Lucius Schoenbaum May 31, 2026
