tracker

Tracker for monitoring mobile ion trajectories during kMC simulations.

exception kmcpy.simulator.tracker.CallbackExecutionError

Raised when an attached property callback fails and cannot be recovered.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class kmcpy.simulator.tracker.Tracker(config, structure, initial_state=None, property_plan=None, default_property_interval=None, hop_state_lookup=None)

Track trajectories and evaluate attached properties for each sampling point.

Built-in result units are available through Tracker.result_units and are also written next to the result CSV by write_results.

apply_property_plan(property_plan, default_interval=None)

Apply a property sampling recipe to this tracker.

Return type:

None

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

Attach one property callback to this tracker.

Return type:

str

attach_spec(spec)

Attach a prevalidated property specification to this tracker.

Return type:

str

clear_attachments()

Remove all user-attached property callbacks.

Return type:

None

detach(name)

Detach a previously attached property callback.

Return type:

None

property dimension: int

Return simulation dimensionality.

property elem_hop_distance: float

Return elementary hop distance.

property frac_coords: ndarray

Return structure fractional coordinates.

get_property_records(name=None)

Retrieve stored callback records.

Return type:

dict[str, list[dict[str, Any]]] | list[dict[str, Any]]

property latt

Return structure lattice.

list_attachments()

Return names of user-attached properties.

Return type:

list[str]

list_property_calculations()

Return enabled/disabled built-ins and currently attached callbacks.

Return type:

dict[str, list[str]]

property mobile_ion_specie: str

Return tracked mobile ion species label.

property occ_initial: list

Return current occupations from the shared simulation state.

property q: float

Return mobile ion charge.

property result_units: dict[str, str]

Return units for built-in result fields.

return_current_info()

Return latest sampled summary values for testing/reporting.

Units follow Tracker.result_units and tuple order is: time, msd, jump_diffusivity, tracer_diffusivity, conductivity, havens_ratio, correlation_factor.

Return type:

tuple[float, float, float, float, float, float, float]

sample_properties(step, sim_time)

Evaluate schedules and execute all attached property callbacks.

Return type:

None

set_global_property_frequency(interval=None, time_interval=None)

Set global sampling defaults for all attached properties.

Return type:

None

set_property_enabled(name, enabled)

Enable or disable a built-in summary field or an attached callback.

Return type:

None

show_current_info()

Log current simulation information and latest sampled summary.

Return type:

None

property temperature: float

Return simulation temperature.

property time: float

Return current simulation time.

update(event, dt)

Update trajectory observables using the current pre-event State.

Return type:

None

update_current_pass(current_pass)

Update current pass index used in logging/output.

Return type:

None

property v: float

Return attempt frequency.

property volume: float

Return structure volume.

write_results(label=None)

Write trajectory arrays, built-in summaries, and custom-property records.

Return type:

None