Guides

Training

Public package status: the Python distributions and desktop installers are not released yet. These pages document an evolving interface, not currently usable install artifacts. View release status.

train is a single, torch-free-to-import door onto the repo’s full training pipeline (model/data/optimizer/scheduler/loop) — the same code path both the training CLI and this facade call.

Training a model

def train(config, **opts) -> dict

config is a path (str/Path to a YAML file, loaded via Config.from_yaml), a dict (wrapped in core.config.Config), or an existing core.config.Config object (passed through unchanged). train returns the trainer’s summary dict with an added "output_dir" key.

import medotter as mo

config = {
    "experiment": {"name": "busi_unet", "seed": 42},
    "model": {"name": "U_Net", "input_channel": 3, "num_classes": 1},
    "dataset": {"BUSI": {"split": "train"}},
    "training": {
        "epochs": 50, "batch_size": 8,
        "optimizer": {"type": "AdamW", "lr": 1e-4},
        "checkpoint": {"save_best": True, "save_last": True},
    },
}
summary = mo.train(config, epochs=1, max_batches=2, output_dir="./runs/smoke")
print(summary["output_dir"], summary.get("total_epochs"))

A real config typically also needs augmentation and logging sections; the dict above is illustrative and deliberately minimal — see train.py-style YAML configs in the repo for a fully worked example.

`**opts`

**opts forwards directly to training.runner.run_training(config, *, output_dir=None, save=True, epochs=None, max_batches=None, resume=None, hf_weights=None, device=None, allow_unsafe=False):

Option	Meaning
`output_dir`	Where to write logs/checkpoints. Defaults to a timestamped directory under the config’s `experiment.output_dir` (or `./results/training`).
`save`	When `False`, gates only model checkpoints — the output directory, logger artifacts (CSV/TensorBoard), and the auto-split manifest are still written.
`epochs`	Overrides `training.epochs` from the config.
`max_batches`	Caps batches per epoch — useful for a fast smoke run.
`resume`	A checkpoint path. Loads that checkpoint into the trainer (optimizer/scheduler state included) before training continues from its saved epoch.
`hf_weights`	Loads weights (not full trainer state) from a Hugging Face repo/path into the model before training starts.
`device`	Picks an already-visible CUDA device, e.g. `"cuda:0"`. To mask GPU memory to specific cards, set `CUDA_VISIBLE_DEVICES` before importing torch — `mo.train` cannot do that after import.
`allow_unsafe`	Default `False`. When `True`, permits the `weights_only=False` pickle fallback for `resume`/`hf_weights` checkpoints — an arbitrary-code-execution risk, so only set it for a checkpoint source you trust.

Resuming from a checkpoint

summary = mo.train(config, epochs=1, max_batches=2, save=True, output_dir="./runs/first")
# ... later, or in a new process ...
resumed = mo.train(config, epochs=1, max_batches=2, resume="./runs/first/checkpoints/last.pth")

Resuming restores the trainer’s epoch counter and optimizer/scheduler state, then continues training toward the (possibly overridden) epochs target — a checkpoint already past that target trains zero additional epochs.

Note: import medotter (and medotter.train as an attribute) is torch-free. Calling train(...) is what pulls in torch and the training stack — the same lazy-import contract as load_model and load_dataset.

Common errors

TypeError — config is not a path, dict, or core.config.Config.
ImportError — surfaces on the call to train, not on import, if torch or the training stack isn’t installed.
Errors from the training loop itself (bad optimizer/scheduler name, shape mismatches, missing dataset) propagate from training.runner.run_training unchanged — train adds no extra validation beyond normalizing config.