fhops.scheduling Package

Scheduling utilities (timeline, mobilisation, system registry).

class fhops.scheduling.BlackoutWindow(*, start_day, end_day, reason=None)

Bases: BaseModel

Represents a continuous period where work is disallowed.

Parameters:

• start_day (int)

• end_day (int)

• reason (str | None)

contains(day)

Parameters:

day (int)

Return type:

bool

end_day: int

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reason: str | None

start_day: int

class fhops.scheduling.BlockDistance(*, from_block, to_block, distance_m)

Bases: BaseModel

Distance between two blocks in metres.

Parameters:

• from_block (str)

• to_block (str)

• distance_m (float)

distance_m: float

from_block: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_block: str

class fhops.scheduling.MachineMobilisation(*, machine_id, walk_cost_per_meter, move_cost_flat, walk_threshold_m=1000.0, setup_cost=0.0)

Bases: BaseModel

Mobilisation parameters for a machine/system.

Parameters:

• machine_id (str)

• walk_cost_per_meter (float)

• move_cost_flat (float)

• walk_threshold_m (float)

• setup_cost (float)

machine_id: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

move_cost_flat: float

setup_cost: float

walk_cost_per_meter: float

walk_threshold_m: float

class fhops.scheduling.MobilisationConfig(*, machine_params, distances=None, default_walk_threshold_m=1000.0, distance_csv=None)

Bases: BaseModel

Complete mobilisation configuration for a scenario.

Parameters:

• machine_params (list[MachineMobilisation])

• distances (list[BlockDistance] | None)

• default_walk_threshold_m (float)

• distance_csv (str | None)

default_walk_threshold_m: float

distance_csv: str | None

distances: list[BlockDistance] | None

machine_params: list[MachineMobilisation]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fhops.scheduling.ShiftDefinition(*, name, hours, shifts_per_day)

Bases: BaseModel

Defines a shift length and count for a machine/job context.

Parameters:

• name (str)

• hours (float)

• shifts_per_day (int)

daily_hours()

Return type:

float

hours: float

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

shifts_per_day: int

class fhops.scheduling.TimelineConfig(*, shifts, blackouts=[], days_per_week=7)

Bases: BaseModel

Aggregates shift definitions and blackout rules for a scenario.

Parameters:

• shifts (list[ShiftDefinition])

• blackouts (list[BlackoutWindow])

• days_per_week (int)

blackouts: list[BlackoutWindow]

days_per_week: int

iter_blackouts()

Return type:

Iterable[BlackoutWindow]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

shifts: list[ShiftDefinition]

Shift/day timeline helpers and blackout scheduling support.

class fhops.scheduling.timeline.BlackoutWindow(*, start_day, end_day, reason=None)

Bases: BaseModel

Represents a continuous period where work is disallowed.

Parameters:

• start_day (int)

• end_day (int)

• reason (str | None)

contains(day)

Parameters:

day (int)

Return type:

bool

end_day: int

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reason: str | None

start_day: int

class fhops.scheduling.timeline.ShiftDefinition(*, name, hours, shifts_per_day)

Bases: BaseModel

Defines a shift length and count for a machine/job context.

Parameters:

• name (str)

• hours (float)

• shifts_per_day (int)

daily_hours()

Return type:

float

hours: float

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

shifts_per_day: int

class fhops.scheduling.timeline.TimelineConfig(*, shifts, blackouts=[], days_per_week=7)

Bases: BaseModel

Aggregates shift definitions and blackout rules for a scenario.

Parameters:

• shifts (list[ShiftDefinition])

• blackouts (list[BlackoutWindow])

• days_per_week (int)

blackouts: list[BlackoutWindow]

days_per_week: int

iter_blackouts()

Return type:

Iterable[BlackoutWindow]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

shifts: list[ShiftDefinition]

Mobilisation distance and setup cost utilities.

class fhops.scheduling.mobilisation.BlockDistance(*, from_block, to_block, distance_m)

Bases: BaseModel

Distance between two blocks in metres.

Parameters:

• from_block (str)

• to_block (str)

• distance_m (float)

distance_m: float

from_block: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_block: str

class fhops.scheduling.mobilisation.MachineMobilisation(*, machine_id, walk_cost_per_meter, move_cost_flat, walk_threshold_m=1000.0, setup_cost=0.0)

Bases: BaseModel

Mobilisation parameters for a machine/system.

Parameters:

• machine_id (str)

• walk_cost_per_meter (float)

• move_cost_flat (float)

• walk_threshold_m (float)

• setup_cost (float)

machine_id: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

move_cost_flat: float

setup_cost: float

walk_cost_per_meter: float

walk_threshold_m: float

class fhops.scheduling.mobilisation.MobilisationConfig(*, machine_params, distances=None, default_walk_threshold_m=1000.0, distance_csv=None)

Bases: BaseModel

Complete mobilisation configuration for a scenario.

Parameters:

• machine_params (list[MachineMobilisation])

• distances (list[BlockDistance] | None)

• default_walk_threshold_m (float)

• distance_csv (str | None)

default_walk_threshold_m: float

distance_csv: str | None

distances: list[BlockDistance] | None

machine_params: list[MachineMobilisation]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

fhops.scheduling.mobilisation.build_distance_lookup(config)

Return symmetric distance lookup from mobilisation config.

Parameters:

config (MobilisationConfig | None)

Return type:

dict[tuple[str, str], float]

Harvest system registry exports.

class fhops.scheduling.systems.HarvestSystem(system_id, jobs, environment=None, notes=None, role_counts=None, role_headstart_shifts=None, loader_batch_volume_m3=None)

Bases: object

Harvest system definition with ordered jobs.

Parameters:

• system_id (str)

• jobs (Sequence[SystemJob])

• environment (str | None)

• notes (str | None)

• role_counts (Mapping[str, int] | None)

• role_headstart_shifts (Mapping[str, float] | None)

• loader_batch_volume_m3 (float | None)

environment: str | None = None

jobs: Sequence[SystemJob]

loader_batch_volume_m3: float | None = None

notes: str | None = None

role_counts: Mapping[str, int] | None = None

role_headstart_shifts: Mapping[str, float] | None = None

system_id: str

class fhops.scheduling.systems.SystemJob(name, machine_role, prerequisites, productivity_overrides=None)

Bases: object

A single job in a harvest system sequence.

Parameters:

• name (str)

• machine_role (str)

• prerequisites (Sequence[str])

• productivity_overrides (Mapping[str, float | str] | None)

machine_role: str

name: str

prerequisites: Sequence[str]

productivity_overrides: Mapping[str, float | str] | None = None

fhops.scheduling.systems.default_system_registry()

Return the default harvest system registry inspired by Jaffray (2025).

Return type:

Mapping[str, HarvestSystem]

fhops.scheduling.systems.get_system_road_defaults(system_id)

Parameters:

system_id (str)

Return type:

Mapping[str, object] | None

fhops.scheduling.systems.system_productivity_overrides(system, machine_role)

Parameters:

• system (HarvestSystem)

• machine_role (str)

Return type:

dict[str, float | str] | None