Tracker And Output Files

KMC runs the algorithm. State owns the mutable occupations. Tracker observes the trajectory and writes output.

Built-In Outputs

After a normal run, kMCpy writes files such as:

results_<label>.csv.gz
results_units_<label>.json.gz
current_occ_<label>.csv.gz
displacement_<label>.csv.gz
hop_counter_<label>.csv.gz

The results table contains transport summaries sampled during the run. Units are written in the results_units sidecar and are also available in Python:

tracker = run(config)
print(tracker.result_units)
print(tracker.return_current_info())

return_current_info() returns:

(time, msd, jump_diffusivity, tracer_diffusivity, conductivity, havens_ratio, correlation_factor)

Attach Custom Properties

Use custom properties when you need to sample a quantity during the simulation:

from kmcpy import KMC


def vacancy_count(state, step, sim_time):
    return sum(value == 1 for value in state.occupations)

kmc = KMC.from_config(config)
kmc.attach(
    vacancy_count,
    name="vacancy_count",
    interval=10,
    store=True,
)
tracker = kmc.run()

For production workflows, configure property callbacks through Configuration.property_callbacks so the run remains reproducible from the input file.

Output Ownership

The tracker owns sampled records and trajectory summaries. It reads the final occupations from its State; callers do not need to pass final occupations back into write_results().

This keeps the workflow simple:

tracker = run(config)
tracker.write_results(label="extra_label")

For advanced property scheduling and callback serialization, see Attach custom properties.

Next: Analyze Results.