File size: 4,177 Bytes
1baf215 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | # Internal v0.1 contracts
Canonical padded vocabulary F fields, identified by schema FIELD_SPECS (list of FieldSpec).
FieldSpec: name, unit, role ('state'/'action'/'exogenous'), minimum, maximum; type continuous.
SCHEMAS maps family string to ordered field names; indices into FIELD_SPECS never change.
DT_MINUTES = 15; HORIZONS = (1,2,4,8) step offsets.
Episode dataclass: system_id, family_id, schema (list field names), timestamps [T+1], values [T+1,F], observation_mask [T+1,F], actions [T,F] and exogenous [T,F] (zero padded), hidden_parameters dict, seed. states property alias values. Field padding represented by field_mask [F] from schema; action/exogenous observation values may be inserted into values rows for history, at t corresponding to next applied transition. Explicit arrays source of truth.
Episode save/load via save_episode(episode,path), load_episode(path). generate_dataset(output,systems,days,seed,families) writes episodes and manifest.json: episodes [{path,system_id,family_id,split}], generator_version, seed, dt_minutes. Relative episode paths. Split train/validation/test by system with stratification. Simulator: make_simulator(family, seed), .parameters dict, .state, .schema list names, .step(action compact or canonical F-vector, exogenous compact or canonical F-vector, dt_minutes=15) returns compact state, .snapshot(), .restore(snapshot). Exogenous trajectory generator documented by data agent.
Normalization.fit(episodes) only called on training episodes; mean, scale [F] physical values; save(path), load(path), transform(values, mask=None), inverse(values); field deltas standardized using scale (no subtraction of mean). Versioned JSON must include training_system_ids. Bounds are metadata, never hidden capacity.
WindowDataset(episodes, normalization, history_steps=24, future_steps=8, samples=..., seed=...): deterministic torch Dataset sampled windows without hidden metadata. __getitem__ returns float32 tensors:
history [H,F] normalized historical values, history_mask [H,F], history_dt [H] minutes relative to current (ends at 0), current [F] normalized current values, current_mask [F], future_actions [K,F] normalized role-specific values with non-role slots zero, future_exogenous [K,F], future_dt [K] minutes since current (15..120), field_mask [F] bool, field_ids [F] int64, unit_ids [F] int64, role_ids [F] int64, query_fields [Q] int64, query_horizons [Q] float minutes, target [Q] normalized delta, target_mask [Q] float/bool. Q all active state fields x offsets 1,2,4,8. history includes current t and preceding H-1 states, actions t-H+1 through t-1; action/exogenous current unavailable, masked at current. Padding query mask false. Fixed Q = max state fields * 4 across families; padded query_fields 0. No system/family/hidden parameters in model input. Collation default.
models.build_model(kind,config) -> nn.Module. Model forward(batch: dict tensor)-> (delta_mean [B,Q], log_std [B,Q]); supports metadata ids and masks; ignores target keys. config dict history_steps,future_steps,num_fields,d_model,layers,heads,ff_dim,dropout (defaults vocabulary / 128 / 4 / 4 / 512 / 0.0). Kinds transformer/mlp/gru. gaussian_nll(mean,log_std,target,mask).
training.train CLI: --data path --output path --model transformer|mlp|gru --epochs --batch-size --samples --history-steps --seed --device auto|cpu|mps. Save checkpoint.pt with model_kind, model_config, model_state, seed, epoch; normalization.json and run.json with exact split IDs. load_checkpoint(path,device='cpu')->(model,checkpoint). data path manifest.json. Early stopping uses validation only; test never selected on. Validation split can be subdivided by system for disjoint calibration.
Evaluation loads same artifacts and independently sampled test windows. evaluation.benchmark CLI --data --checkpoint --output --samples --device. calibration JSON residual quantile multipliers per field/horizon fitted only to calibration systems; API may only call interval calibrated if present and compatible. Baselines persistence/CatBoost/fitted linear system ID all use identical normalization and partitions. Counterfactual snapshots never passed into neural features.
|