Instruments¶

Describe every registered loader — for print_instruments and docs.

Forget discovery results (tests, and after installing a plugin).

Pick a loader for source, or return None if none applies.

Routing order (architecture plan §5.3): an explicit instrument wins; otherwise candidates are narrowed by suffix and confirmed with the loader's own cheap can_load() sniff.

The registered loaders, keyed by name. Discovers on first use.

Register a loader directly, bypassing entry points.

For tests and for notebook-defined loaders. Packaged loaders should declare an entry point instead so they are found without a call.

Normalize a parsed vendor frame into harmonized native raw.

Parameters:

• vendor_frame (Any) –

  what the loader's parse() produced — a polars frame, or a pandas frame (converted here, so legacy parsers can be reused unchanged during the port).

• declarations (LoaderDeclarations) –

  the loader's declarations.

• test_id (int, default: 0 ) –

  identity for the rows of this test.

• strict (bool, default: True ) –

  run validate_raw_frame strictly. The two sanctioned warn-only escape hatches (local_instrument and friends, conventions plan §4) pass strict=False.

Returns:

• DataFrame –

  A polars frame in the harmonized-raw schema.

Raises:

• LoaderError –

  if the frame cannot be normalized or fails validation.

Convert cumulative columns to the harmonized-raw convention.

The target (harmonized-raw spec, Capacity convention) is cumulative per cycle, per direction: within a cycle the value accumulates across that cycle's steps, and resets to 0 at each cycle boundary. The summary path depends on this — per-cycle capacity is read from the cycle's last datapoint — so a wrong granularity here corrupts every capacity downstream without raising anything.

Conversions:

PER_CYCLE Already the target. Left untouched. PER_TEST Never resets, so the whole history is baked in. Subtract the value the column held entering each cycle. PER_STEP Resets each step, so within a cycle we must re-accumulate: add the running total of the completed steps of that cycle.

Parameters:

• raw (DataFrame) –

  frame already renamed to native columns.

• declarations (LoaderDeclarations) –

  carries reset_granularity per column.

Returns:

• DataFrame –

  A new frame; the input is not mutated.

Fill the provenance fields a loader is not allowed to fill itself.

The loader knows what the file says; only the framework knows where the file came from and when it was read (architecture plan §5.4).

Build validated declarations from an existing configuration module.

Parameters:

• config (ModuleType | Any) –

  a cellpy.readers.instruments.configurations.* module, or a live ModelParameters instance (a loader's config_params). Both expose the same attribute names, which is what lets the port derive declarations from a loader that is already running.

• reset_granularity (dict[str, ResetGranularity] | None, default: None ) –

  overrides for columns whose vendor granularity is not the harmonized-raw default. Read the vendor's data before setting one — a wrong value here silently rescales capacities.

• post_hooks (tuple, default: () ) –

  vendor-quirk callables (e.g. capacity splitting).

• timezone (str | None, default: None ) –

  IANA zone for naive vendor timestamps.

Returns:

• LoaderDeclarations –

  A validated :class:LoaderDeclarations.

Raises:

• LoaderError –

  if the derived declarations do not validate — which is the point: it happens at import of the configuration, not mid-load.

Build hand-written loaders' declarations from their module renaming dict.

Shared by the Arbin SQL variants (arbin_sql, arbin_sql_csv, arbin_sql_xlsx, arbin_sql_7), which each carry a {legacy_attr -> vendor} dict just like a configuration but resolve it in code rather than through a configurations/* module.

The dict is first restricted to real cellpy headers, reproducing what the legacy _post_process does when it renames by iterating arbin_headers_normal: the Arbin dicts also carry non-header aliases (e.g. acr_txt, which is not a header) that collide with a real header on the same vendor column — acr_txt and internal_resistance_txt both name Internal_Resistance(Ohm). Deriving from the unfiltered dict would let the first-declared non-header alias win and mis-route the column; the legacy path never sees the alias at all, so neither should the derivation.

Split a configuration's renaming dict into native, passthrough, unknown.

Parameters:

• renaming (dict[str, str]) –

  legacy_attr -> vendor column, as the configurations declare it.

Returns:

• dict[str, str] –

  (column_map, passthrough, unknown) where column_map is

• dict[str, str] –

  vendor → native for attributes cellpy-core can map, passthrough is

• list[str] –

  vendor → legacy column name for real data with no native column yet,

• tuple[dict[str, str], dict[str, str], list[str]] –

  and unknown lists attributes that are neither — a configuration

• tuple[dict[str, str], dict[str, str], list[str]] –

  naming something no longer recognised anywhere.

A vendor column claimed by more than one legacy attribute is ambiguous: only one target can win, and the other is silently lost. maccor_txt_one does this today, mapping Watt-hr to both power_txt and charge_energy_txt. The first declaration wins here, matching what the legacy path is observed to produce, and the collision is logged rather than resolved silently.

Resolve {{ unit }} placeholders in vendor column names.

Neware spells its columns with the unit baked in — Current({{ current }}) becomes Current(A). The legacy update_headers_with_units post-processor did this by mutating config_params in place at load time, which makes the substitution a side effect of having loaded something.

That side effect does not reach the configuration module: a ModelParameters instance carries its own copy. So deriving declarations from a module yielded seven neware vendor names still spelled Current({{ current }}) — names no file contains, so those columns were silently unmapped, while deriving from a post-load config_params worked. Same configuration, different answer depending on what had run first.

Doing it here makes the derivation self-contained and order-independent.

Parameters:

• renaming (dict[str, str]) –

  legacy_attr -> vendor column; not mutated.

• config (Any) –

  the configuration, for unit_labels / raw_units.

Returns:

• dict[str, str] –

  A new dict with placeholders resolved.

Raises:

• LoaderError –

  if a placeholder names a unit the configuration does not define. Legacy substituted the string "None", producing a column name that matches nothing — a silent unmapped column rather than an error.

Routing calls can_load(); a slow sniff makes every load slow.

The class declares what the registry needs to route it.

Loaders are stateless across calls.

Run the whole conformance suite for one loader against one fixture.

Parameters:

• loader_cls (type) –

  the loader class (the registry routes on class-level capability metadata, so that is what is checked).

• fixture (Path) –

  a small committed sample file the loader can parse.

• **kwargs (Any, default: {} ) –

  forwarded to load().

Raises:

• AssertionError –

  naming the contract promise that was broken.

The loader fills what the file knows — never provenance.

The frame is polars, in the harmonized-raw shape.

Check 7 — reset-granularity sanity on a harmonized raw frame.

A wrong reset_granularity declaration does not raise; it silently rescales capacities (loader plan §5). The full value-parity property test lives in tests/test_harmonize.py; this kit check is the cheap structural gate every conforming loader must pass: when cumulative capacity columns are present, the last value of each cycle is finite and the per-cycle series has one row per distinct cycle_num.

load() returns a tuple of LoaderResult — always a tuple.

raw_units is a validated CellpyUnits, not an ad-hoc dict.