visualdynamics.io.sep005

sep005

SEP 005 — the sdypy ecosystem's unified timeseries, in and out.

SEP 005 (SEP 5 <https://github.com/sdypy/sdypy/blob/main/docs/seps/sep-0005.rst>_) is the interchange standard of the open-source sdypy project: one plain dict per timeseries — data shaped (n,) or (m, n), a name, per-channel unit_str, and either a sampling frequency fs or a time vector — with a list of dicts for several series. It is an in-memory standard, not a file format, so this module converts objects rather than registering a file importer: from_sep005 turns the dicts a sdypy package hands over into TimeHistory objects, and TimeHistory.to_sep005 goes the other way.

Nothing here imports anything from sdypy — the standard is the dict, and staying import-free is what keeps the licence boundary trivial.

Timeseries are the standard's whole scope, which is why only TimeHistory converts: sdypy has no richer exchange form for FRFs, PSDs or geometry, so those stay in .vdyn / UNV.

Functions:

Name	Description
from_sep005	SEP 005 timeseries into TimeHistory objects.

Functions:

from_sep005

from_sep005(
    timeseries: dict[str, Any] | list[dict[str, Any]],
) -> Any

SEP 005 timeseries into TimeHistory objects.

history = visualdynamics.from_sep005({'data': y, 'fs': 256.0,
                                      'name': 'run 4',
                                      'unit_str': 'm/s²'})

One dict returns one TimeHistory; a list — the standard's form for several series — returns {name: TimeHistory}, numbering a repeated name the way the project tree would.

unit_str entries that parse are declared on the object (values converted to SI, exactly as define_units would), because the producer stated them; one that does not parse leaves that channel's values raw with the claim kept in dimension_hint, where quantity also lands when there is no unit at all. Nothing is ever scaled by a guess.

Refused, with the reason: a series with no data, with neither fs nor time, a time vector of the wrong length, or a channel_name list that does not match the channel count.

Source code in src/visualdynamics/io/sep005.py

def from_sep005(timeseries: dict[str, Any] | list[dict[str, Any]]
                ) -> Any:
    """SEP 005 timeseries into `TimeHistory` objects.

        history = visualdynamics.from_sep005({'data': y, 'fs': 256.0,
                                              'name': 'run 4',
                                              'unit_str': 'm/s²'})

    One dict returns one `TimeHistory`; a list — the standard's form
    for several series — returns ``{name: TimeHistory}``, numbering a
    repeated name the way the project tree would.

    ``unit_str`` entries that parse are *declared* on the object
    (values converted to SI, exactly as `define_units` would), because
    the producer stated them; one that does not parse leaves that
    channel's values raw with the claim kept in `dimension_hint`, where
    ``quantity`` also lands when there is no unit at all. Nothing is
    ever scaled by a guess.

    Refused, with the reason: a series with no ``data``, with neither
    ``fs`` nor ``time``, a ``time`` vector of the wrong length, or a
    ``channel_name`` list that does not match the channel count.
    """
    if isinstance(timeseries, dict):
        return _one(timeseries)
    out: dict[str, Any] = {}
    for series in timeseries:
        name = str(series.get('name', 'Time History')) or 'Time History'
        unique, n = name, 1
        while unique in out:
            n += 1
            unique = f'{name} ({n})'
        out[unique] = _one(series)
    return out