config

Field Discovery

Use Configuration.help_fields() to list valid field names and see how fields are split between system_config and runtime_config.

from kmcpy.simulator.config import Configuration

Configuration.help_fields()

Clean simulation configuration classes with clear separation of concerns.

Architecture:

• SystemConfig: Physical system definition (immutable)

• RuntimeConfig: Simulation runtime fields (immutable)

• Configuration: Complete simulation setup (immutable)

• State: Mutable state during execution

This module provides field routing and configuration management for kinetic Monte Carlo simulations. It handles both system fields (what you’re simulating) and runtime fields (how you run the simulation).

class kmcpy.simulator.config.Configuration(system_config=None, runtime_config=None, **kwargs)

Complete simulation configuration combining system and runtime fields.

as_dict(include_loader_paths=False)

Convert to a recorded dictionary.

By default, loader-only path fields such as structure_file, model_file, event_file, and initial_state_file are omitted because they are only needed to construct the loaded simulation inputs. Use include_loader_paths=True when writing a reloadable simulation input file.

Return type:

dict[str, Any]

as_input_dict()

Return a reloadable input dictionary including loader path fields.

Return type:

dict[str, Any]

as_record_dict()

Return metadata suitable for recording after simulation inputs are loaded.

Return type:

dict[str, Any]

property attempt_frequency: float

Access attempt frequency directly.

property builtin_property_enabled: dict[str, bool]

Access built-in property enable/disable map directly.

property convert_to_primitive_cell: bool

Access convert to primitive cell directly.

property dimension: int

Access dimension directly.

property elementary_hop_distance: float

Access elementary hop distance directly.

property equilibration_passes: int

Access equilibration passes directly.

property event_file: str

Access event file directly.

classmethod field_units()

Return configured units for numeric configuration fields.

Return type:

dict[str, str]

classmethod from_dict(config_dict)

Create from dictionary.

Return type:

Configuration

classmethod from_file(filename, section=None, task_type=None)

Load Configuration from a JSON/YAML file.

Parameters:

• filename (str | Path) – Path to configuration file (.json, .yaml, .yml).

• section (str | None) – Optional top-level section to load from a YAML workflow file.

• task_type (str | None) – Optional task type for registry-style sections.

Return type:

Configuration

classmethod help_fields()

Print available configuration fields and where they are routed.

property initial_occupations: list | None

Access initial occupations directly.

property initial_state_file: str | None

Access initial state file directly.

property kmc_passes: int

Access KMC passes directly.

classmethod load(file_path)

Loads a class from a provided json file.

Parameters:

file_path (os.PathLike) – The json file to load from.

Returns:

An instance of the class being reloaded.

Return type:

MSONable

property mobile_ion_charge: float

Access mobile ion charge directly.

property mobile_ion_specie: str

Access mobile ion species directly.

property model_file: str

Access model file directly.

property model_type: str

Access model type directly.

property name: str

Access simulation name directly.

property property_callbacks: list[dict[str, Any]]

Access callback attachment specs directly.

property property_sampling_interval: int | None

Access global property sampling step interval directly.

property property_sampling_time_interval: float | None

Access global property sampling time interval directly.

property random_seed: int | None

Access random seed directly.

save(json_path, mkdir=True, json_kwargs=None, pickle_kwargs=None, strict=True)

Utility that uses the standard tools of MSONable to convert the class to json format, but also save it to disk. In addition, this method intelligently uses pickle to individually pickle class objects that are not serializable, saving them separately. This maximizes the readability of the saved class information while allowing _any_ class to be at least partially serializable to disk.

For a fully MSONable class, only a class.json file will be saved to the location {save_dir}/class.json. For a partially MSONable class, additional information will be saved to the save directory at {save_dir}. This includes a pickled object for each attribute that e serialized.

Parameters:

• file_path (os.PathLike) – The file to which to save the json object. A pickled object of the same name but different extension might also be saved if the class is not entirely MSONable.

• mkdir (bool) – If True, makes the provided directory, including all parent directories.

• json_kwargs (dict) – Keyword arguments to pass to the serializer.

• pickle_kwargs (dict) – Keyword arguments to pass to pickle.dump.

• strict (bool) – If True, will not allow you to overwrite existing files.

property site_mapping: dict | None

Access site mapping directly.

property structure_file: str

Access structure file directly.

summary()

Human-readable summary.

Return type:

str

property supercell_shape: tuple[int, int, int]

Access supercell shape directly.

property temperature: float

Access temperature directly.

to(filename, include_loader_paths=False, section=None, task_type='default', **kwargs)

Write Configuration to a JSON/YAML file.

Parameters:

• filename (str | Path) – Output file path (.json, .yaml, .yml).

• include_loader_paths (bool) – Include loader-only path fields for reloadable input files. The default recorded form omits them.

• section (str | None) – Optional top-level YAML section for workflow files.

• task_type (str) – Registry-style task type when section is provided.

• **kwargs – Additional formatting arguments, such as indent for JSON.

Return type:

None

to_json()

Returns a json string representation of the MSONable object.

Return type:

str

unsafe_hash()

Returns an hash of the current object. This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object

validate()

Validate the configuration.

Return type:

bool

classmethod validate_monty_v1(_MSONable__input_value)

Pydantic validator with correct signature for pydantic v1.x

classmethod validate_monty_v2(_MSONable__input_value, _)

Pydantic validator with correct signature for pydantic v2.x

which_config(field_name)

Show which sub-config contains a field.

Return type:

str

with_runtime_changes(**changes)

Create new config with runtime field changes.

Return type:

Configuration

with_system_changes(**changes)

Create new config with system field changes.

Return type:

Configuration

class kmcpy.simulator.config.RuntimeConfig(temperature=300.0, attempt_frequency=10000000000000.0, equilibration_passes=1000, kmc_passes=10000, random_seed=None, name='DefaultSimulation', property_sampling_interval=None, property_sampling_time_interval=None, builtin_property_enabled=<factory>, property_callbacks=<factory>)

Simulation runtime configuration - completely immutable. This defines HOW you’re simulating.

as_dict()

Convert to a JSON/YAML-serializable dictionary.

Return type:

dict[str, Any]

class kmcpy.simulator.config.SystemConfig(structure_file='', supercell_shape=(1, 1, 1), dimension=3, mobile_ion_specie='Li', mobile_ion_charge=1.0, elementary_hop_distance=1.0, model_type='composite_lce', model_file='', event_file='', site_mapping=None, convert_to_primitive_cell=False, initial_state_file=None, initial_occupations=None)

Physical system configuration - completely immutable. This defines WHAT you’re simulating.

as_dict(include_loader_paths=False)

Convert to a JSON/YAML-serializable dictionary.

File path fields are loader inputs, not intrinsic system metadata. They are omitted by default from recorded payloads and can be included when writing a reloadable input file.

Return type:

dict[str, Any]