Configuration

ConfigClass

ConfigClass(*args: Any, **kwargs: Any)

Bases: dict

Global configuration dictionary for Fennel package.

This class extends Python's built-in dict to provide configuration management with YAML file loading and dictionary merging capabilities. The configuration stores all parameters needed for light yield calculations.

Parameters:

Name	Type	Description	Default
*args	Any	Positional arguments passed to dict constructor	()
**kwargs	Any	Keyword arguments passed to dict constructor	{}

Attributes:

Name	Type	Description
All configuration keys from _baseconfig, including		general : dict General settings (random seed, logging, JAX mode) scenario : dict Simulation scenario (medium, parametrization) pdg id : dict Mapping of PDG IDs to particle names mediums : dict Medium properties (refractive index, density, radiation length) simulation : dict Simulation parameters (particle lists, interactions) track : dict Track parametrization parameters em_cascade : dict EM cascade parametrization parameters hadron_cascade : dict Hadron cascade parametrization parameters advanced : dict Advanced settings (grids, thresholds)

Examples:

Access configuration values:

>>> from fennel import config
>>> config["general"]["random state seed"]
1337
>>> config["mediums"]["water"]["refractive index"]
1.333

Modify configuration:

>>> config["general"]["jax"] = True
>>> config["general"]["random state seed"] = 42

Load from YAML file:

>>> config.from_yaml("my_config.yaml")

Update from dictionary:

>>> user_config = {"general": {"jax": False}}
>>> config.from_dict(user_config)

Notes

• Configuration changes affect the entire package globally
• Set parameters before creating Fennel() instance
• Random seed should be set for reproducible results

Initialize the configuration dictionary.

Source code in fennel/config.py

def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the configuration dictionary."""
    super().__init__(*args, **kwargs)

from_dict

from_dict(user_dict: Dict[str, Any]) -> None

Update configuration from a dictionary.

Merges the user dictionary with the current configuration. Existing keys are overwritten, new keys are added.

Parameters:

Name	Type	Description	Default
user_dict	dict	Dictionary containing configuration updates	required

Examples:

>>> user_config = {
...     "general": {"jax": True, "random state seed": 42},
...     "scenario": {"medium": "ice"}
... }
>>> config.from_dict(user_config)

Notes

Deep nesting is preserved during merge. Only provide the specific keys you want to override, not the entire configuration structure.

Source code in fennel/config.py

def from_dict(self, user_dict: Dict[str, Any]) -> None:
    """
    Update configuration from a dictionary.

    Merges the user dictionary with the current configuration.
    Existing keys are overwritten, new keys are added.

    Parameters
    ----------
    user_dict : dict
        Dictionary containing configuration updates

    Examples
    --------
    >>> user_config = {
    ...     "general": {"jax": True, "random state seed": 42},
    ...     "scenario": {"medium": "ice"}
    ... }
    >>> config.from_dict(user_config)

    Notes
    -----
    Deep nesting is preserved during merge. Only provide the specific
    keys you want to override, not the entire configuration structure.
    """
    self.update(user_dict)

from_yaml

from_yaml(yaml_file: Union[str, Path]) -> None

Update configuration from a YAML file.

Merges the contents of the YAML file with the current configuration. Existing keys are overwritten, new keys are added.

Parameters:

Name	Type	Description	Default
yaml_file	str or Path	Path to YAML configuration file	required

Raises:

Type	Description
FileNotFoundError	If the YAML file doesn't exist
YAMLError	If the YAML file is malformed

Examples:

>>> config.from_yaml("custom_config.yaml")
>>> config.from_yaml(Path("configs/experiment1.yaml"))

Notes

The YAML file should have the same structure as the base config. Only provide keys you want to override.

Source code in fennel/config.py

def from_yaml(self, yaml_file: Union[str, Path]) -> None:
    """
    Update configuration from a YAML file.

    Merges the contents of the YAML file with the current configuration.
    Existing keys are overwritten, new keys are added.

    Parameters
    ----------
    yaml_file : str or Path
        Path to YAML configuration file

    Raises
    ------
    FileNotFoundError
        If the YAML file doesn't exist
    yaml.YAMLError
        If the YAML file is malformed

    Examples
    --------
    >>> config.from_yaml("custom_config.yaml")
    >>> config.from_yaml(Path("configs/experiment1.yaml"))

    Notes
    -----
    The YAML file should have the same structure as the base config.
    Only provide keys you want to override.
    """
    yaml_config = yaml.load(open(yaml_file), Loader=yaml.SafeLoader)
    self.update(yaml_config)