Utilities (pypielm.utils)

Utilities: reproducibility helpers, YAML config loader, and type coercions.

Implemented across Steps 2 (reproducibility) and 10 (config / CLI).

pypielm.utils.seed_everything(seed=42, *, deterministic=True)

Set all relevant random seeds for full reproducibility.

Seeds: Python random, numpy.random, PyTorch CPU, PyTorch CUDA, and Apple MPS (seeded implicitly via torch.manual_seed()).

Parameters:

• seed (int) – Integer seed value.

• deterministic (bool) – If True, enables deterministic CUDA algorithms (may reduce performance but guarantees reproducibility). Has no effect on MPS (MPS operations are always deterministic).

Return type:

None

pypielm.utils.get_device(prefer_cuda=True, prefer_mps=True)

Return the best available torch.device.

Priority order: CUDA > MPS (Apple Silicon) > CPU.

Parameters:

• prefer_cuda (bool) – If True and CUDA is available, returns a CUDA device.

• prefer_mps (bool) – If True and Apple MPS is available (and CUDA is not), returns an MPS device. Ignored when prefer_cuda=True and CUDA is present.

Return type:

device

Returns:

A torch.device.

Config Loader

YAML-based experiment configuration loader and runner.

class pypielm.utils.config.ExperimentConfig(model='core_pielm', model_kwargs=<factory>, data=<factory>, pde=<factory>, seed=42, device='cpu', output_dir='runs/')

Bases: object

Fully-specified configuration for a single PyPIELM experiment.

All fields can be populated from a YAML file via load_config().

Parameters:

• model (str) – Registered model name (e.g. 'core_pielm').

• model_kwargs (dict[str, Any]) – Keyword arguments forwarded to the model constructor.

• data (dict[str, Any]) – Data loading specification (source, path, split ratios).

• pde (dict[str, Any]) – PDE configuration (operator, collocation, n_collocation).

• seed (int) – Global random seed (passed to seed_everything()).

• device (str) – Target device string.

• output_dir (str) – Directory for saving artefacts (model, results, figures).

Example YAML:

model: core_pielm
model_kwargs:
  hidden_dim: 300
  ridge_lambda: 1.0e-8
data:
  source: pinnacle
  path: data/poisson_classic.dat
  val_ratio: 0.1
  test_ratio: 0.2
pde:
  operator: laplacian
  collocation: LHSSampler
  n_collocation: 1000
seed: 42
device: cpu
output_dir: runs/poisson_classic_core/

model: str = 'core_pielm'

model_kwargs: dict[str, Any]

data: dict[str, Any]

pde: dict[str, Any]

seed: int = 42

device: str = 'cpu'

output_dir: str = 'runs/'

pypielm.utils.config.load_config(path)

Load and validate an experiment config from a YAML file.

Parameters:

path (str | Path) – Path to the .yaml configuration file.

Return type:

ExperimentConfig

Returns:

A populated ExperimentConfig instance.

Raises:

• FileNotFoundError – If path does not exist.

• ValueError – If required fields are missing or values are invalid.

pypielm.utils.config.run_experiment(config)

Execute a single experiment defined by config.

Steps performed:

1. Seed everything via seed_everything().

2. Load data via auto_load() (if data.path is given) or build a synthetic dataset for dry-runs.

3. Instantiate the model from the registry.

4. Resolve PDE operator and collocation sampler.

5. Call model.fit(dataset, ...).

6. Evaluate metrics on the test split.

7. Save checkpoint + results.json to output_dir.

Parameters:

config (ExperimentConfig) – A validated ExperimentConfig.

Returns:

• 'metrics': dict of metric name → float.

• 'config': the config as a plain dict.

• 'artifacts': list of paths of saved files.

Return type:

Dictionary with keys

Reproducibility

Utility helpers: reproducibility and device selection.

pypielm.utils.reproducibility.seed_everything(seed=42, *, deterministic=True)

Set all relevant random seeds for full reproducibility.

Seeds: Python random, numpy.random, PyTorch CPU, PyTorch CUDA, and Apple MPS (seeded implicitly via torch.manual_seed()).

Parameters:

• seed (int) – Integer seed value.

• deterministic (bool) – If True, enables deterministic CUDA algorithms (may reduce performance but guarantees reproducibility). Has no effect on MPS (MPS operations are always deterministic).

Return type:

None

pypielm.utils.reproducibility.get_device(prefer_cuda=True, prefer_mps=True)

Return the best available torch.device.

Priority order: CUDA > MPS (Apple Silicon) > CPU.

Parameters:

• prefer_cuda (bool) – If True and CUDA is available, returns a CUDA device.

• prefer_mps (bool) – If True and Apple MPS is available (and CUDA is not), returns an MPS device. Ignored when prefer_cuda=True and CUDA is present.

Return type:

device

Returns:

A torch.device.