property

Shared scheduling and property callback utilities.

class kmcpy.simulator.property.PropertyPlan(interval=None, time_interval=None, builtin_enabled=None)

Property sampling recipe for a KMC run.

The plan stores user intent: global cadence, enabled built-in fields, and custom callback registrations. Runtime sampling state and stored records belong to the Tracker.

attach(func, interval=None, time_interval=None, name=None, store=True, max_records=None, on_error=None, enabled=True)

Register a custom property callback in the plan.

Return type:

str

property builtin_enabled: dict[str, bool]

Return a copy of built-in property enablement flags.

clear_attachments()

Remove all custom callbacks while preserving built-in settings.

Return type:

None

detach(name)

Remove a custom property callback from the plan.

Return type:

None

fresh_attachment_specs()

Return callback specs with runtime sampling counters reset.

Trackers mutate last_trigger_step and last_trigger_time while sampling, so each run must receive fresh spec objects.

Return type:

list[PropertySpec]

property global_interval: int | None

Return the configured global step interval.

property global_time_interval: float | None

Return the configured global simulation-time interval.

list_attachments()

Return registered custom callback names.

Return type:

list[str]

list_property_calculations()

Return enabled/disabled built-ins and custom callbacks.

Return type:

dict[str, list[str]]

set_frequency(interval=None, time_interval=None)

Set the global sampling cadence for built-ins and callbacks.

Return type:

None

set_property_enabled(name, enabled)

Enable or disable one built-in field or custom callback.

Return type:

None

class kmcpy.simulator.property.PropertyRecord(name, step, time, value)

Stored callback output for one sampling point.

class kmcpy.simulator.property.PropertySpec(name, callback, interval=None, time_interval=None, store=True, max_records=None, enabled=True, on_error=None, last_trigger_step=0, last_trigger_time=None)

Property callback registration metadata.

kmcpy.simulator.property.append_record(records, spec, step, sim_time, value)

Append one callback record and enforce record limits.

Return type:

None

kmcpy.simulator.property.compute_transport_properties(displacement, hop_counter, *, sim_time, dimension, n_mobile_ion_specie, elementary_hop_distance, volume, mobile_ion_charge, temperature, enabled=None)

Compute built-in transport properties from trajectory state.

Return type:

dict[str, float]

Unit conventions:

displacement: Angstrom sim_time: s elementary_hop_distance: Angstrom volume: Angstrom^3 mobile_ion_charge: units of the absolute elementary charge temperature: K

Returned units are defined by TRANSPORT_PROPERTY_UNITS:

msd: Angstrom^2 jump_diffusivity: cm^2/s tracer_diffusivity: cm^2/s conductivity: mS/cm havens_ratio: dimensionless correlation_factor: dimensionless

kmcpy.simulator.property.describe_property_calculations(*, builtin_enabled, attached_properties)

Return enabled/disabled built-ins and custom callbacks.

Return type:

dict[str, list[str]]

kmcpy.simulator.property.make_property_spec(func, *, interval=None, time_interval=None, name=None, store=True, max_records=None, on_error=None, enabled=True, existing_names=None)

Validate callback metadata and return a property sampling spec.

Return type:

PropertySpec

kmcpy.simulator.property.set_property_enabled_flag(*, builtin_enabled, attached_properties, name, enabled)

Enable or disable one built-in metric or custom callback.

Return type:

None

kmcpy.simulator.property.should_trigger(step, sim_time, interval, time_interval, last_trigger_time)

Return whether a scheduled property should execute.

Return type:

bool

kmcpy.simulator.property.validate_max_records(max_records)

Validate storage truncation parameter.

Return type:

None

kmcpy.simulator.property.validate_schedule(interval, time_interval)

Validate callback scheduling parameters.

Return type:

None