migrate

Migrate legacy PET config files to the current schema.

Two changes are handled.

The two-element daalg key, which packed an assimilation family and an update method into a list, is replaced by a single scheme key naming the algorithm::

daalg = ["esmda", "esmda"]   ->   scheme = "esmda"

The second element was the one that actually selected the class, so that is what carries over. Where the two elements disagree the second still wins, and the migration reports it so the change is visible rather than silent.

analysisdebug is renamed to savedata, matching popt and describing what the key does -- it names the variables recorded each iteration, which is a record of the run rather than a debugging aid::

analysisdebug = [...]   ->   savedata = [...]

The old spelling still works at runtime, with a deprecation warning, so this one is a tidy-up rather than a required migration. The output files did change name, from debug_analysis_step_{i}.npz to assimilation_result_{i}.npz, which no config rewrite can paper over: any post-processing that globs the old pattern needs updating by hand.

Formatting is preserved. The rewrite is a surgical edit of the daalg assignment itself, not a parse-and-redump of the file, because a round trip through a TOML/YAML writer discards everything that is not data: comments, commented-out alternative blocks, indentation, inline tables, quote style and list layout. Real PET configs carry all of those -- a commented-out localization block that gets toggled against the active one is a common pattern, and silently deleting it would be unacceptable.

If the surgical edit cannot find the assignment (an unusual layout), the migration falls back to the round trip and warns that formatting will be lost, rather than failing or destroying the file silently.

MigrationReport

What a migration changed, or would change.

changed: bool

Whether the migration changed anything.

migrate_config(path, *, dry_run=False, backup=True)

Migrate a config file to the current schema.

Parameters:

Name	Type	Description	Default
path	str or Path	Path to a .toml or .yaml config file.	required
dry_run	bool	Report what would change without writing anything.	False
backup	bool	Keep the original alongside the migrated file as <name>.bak.	True

Returns:

Type	Description
MigrationReport

migrate_section(section, report)

Migrate one config section in place, recording what changed.