Protocols and schedules

schedule

Temperature schedules: ramps and holds, whole steps, the target per step (SPEC §7.2, §7.6 "Schedules").

A Schedule is timestep-free: segments in ps. Schedule.resolve(timestep_fs) rounds each segment to whole steps (half up) and records the boundaries, the total and the rounded durations and rates. The target is piecewise linear in the step. Step n of a segment uses the target at the step's end point, as the research engine does ("update the target every timestep using that step's endpoint", docs/protocol.md), so the target changes every step on a ramp and never on a hold. It reaches the integrator through Integrator.set_temperature before the step (TargetFill), never as an event.

Each ramp interpolates from its colder end, T_low + (T_high - T_low) * w. This reproduces the research engine's float expressions bit for bit: peak * n / H when heating from 0 K and final + (peak - final) * (H + C - n) / C when cooling.

ScheduleState is the schedule position: the restart record of SimulationState.protocol.

Schedule dataclass

A sequence of segments; + concatenates and refuses a temperature jump.

duration_ps property

duration_ps: float

The requested duration (before rounding).

resolve

resolve(timestep_fs: float) -> ResolvedSchedule

Whole steps at timestep_fs.

Segment dataclass

One ramp or hold as requested: ps or (ramps only) rate_K_per_ps, never both.

duration_ps property

duration_ps: float

The requested duration (before rounding to whole steps).

phase property

phase: str

heating, cooling or hold: the thermo file's phase column (workflow.schedule_phase).

to_data

to_data() -> dict[str, Any]

The segment as profile data (segment_from_data reads it back).

ramp

ramp(
    start_K: float,
    end_K: float,
    *,
    ps: float | None = None,
    rate_K_per_ps: float | None = None,
) -> Schedule

A linear ramp from start_K to end_K, over ps or at rate_K_per_ps (signed).

hold

hold(temperature_K: float, *, ps: float) -> Schedule

temperature_K for ps.

profiles

Run profiles as data (SPEC §10.5): today's slow, fast, ultrafast and anneal.

The research engine's workflow.PROFILES: the schedule, the output intervals, the initial relaxation and, for anneal, the quench settings (docs/assets/Simulated_Annealing.txt). The relaxation and quench settings are data only here; nothing in this module runs them.

Profiles from files: TOML (tomllib, tomli before Python 3.11) or YAML (PyYAML's safe_load only, imported when needed).

PROFILES module-attribute

PROFILES: Mapping[str, Profile] = MappingProxyType(
    {
        "slow": _research_profile("slow", 30.0, 240.0),
        "fast": _research_profile("fast", 3.0, 24.0),
        "ultrafast": _research_profile(
            "ultrafast", 1.0, 8.0
        ),
        "anneal": _research_profile(
            "anneal",
            20.0,
            250.0,
            peak_K=1000.0,
            final_K=250.0,
            interval=20,
            relax_fmax=0.01,
            quench={
                "min_K": 500.0,
                "bin_K": 100.0,
                "per_bin": 2,
                "fmax": 0.01,
                "optimizer": DEFAULT_OPTIMIZER,
                "max_steps": 5000,
            },
        ),
    }
)

Profile dataclass

A named schedule with its output intervals, initial relaxation and quench settings.

relax_fmax 0 means no initial relaxation (fixed cell, eV/Å). quench is None or a mapping with QUENCH_KEYS (frames per bin_K bin of the target from min_K, quenched to fmax with optimizer, at most max_steps). Optimizer names are resolved (resolve_optimizer). Relaxation and quench keep the cell fixed; after NPT each frame is quenched at its own cell.

ensemble is "NVT" or "NPT" (fm.md's; any case). pressure_GPa is NPT's constant hydrostatic target, None for NVT and 0 GPa by default for NPT; pressure schedules are refused until the pressure setter (plan task 3b-T05). dispersion is "none" or "d3bj" (fm.md's, SPEC §7.7).

md_options

md_options() -> dict[str, Any]

fm.md's schedule, ensemble, pressure and dispersion arguments of this profile.

load_profile

load_profile(path: str | Path) -> Profile

A profile from a .toml, .yaml or .yml file (YAML through safe_load only).