`visualdynamics.io.sdynpy_npz`¶

sdynpy_npz ¶

Importer for sdynpy native geometry files (.npz).

The format is a numpy .npz archive with four structured arrays. Field layout (np.lib.format is self-describing; read with np.load):

node: id, coordinate (3,), color, def_cs, disp_cs
coordinate_system: id, name, color, cs_type, matrix (4, 3) — rows 0-2 are the rotation, row 3 the origin (length units)
traceline: id, color, description, connectivity (object: node id array)
element: id, type (UFF 2412 descriptor code), color, connectivity (object)

The file carries no units. length_unit may be given to declare them at import; otherwise the geometry arrives unit-less.

Functions:

Name	Description
`load`	sdynpy geometry files carry no units; without `length_unit` the
`save`	Write a geometry in sdynpy's own .npz layout.

Classes¶

Functions:¶

load ¶

load(path: str | PathLike, length_unit: str | None = None) -> Geometry

sdynpy geometry files carry no units; without length_unit the geometry imports with its raw coordinates for the user to define later.

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

def load(path: str | os.PathLike, length_unit: str | None = None) -> Geometry:
    """sdynpy geometry files carry no units; without `length_unit` the
    geometry imports with its raw coordinates for the user to define later."""
    scale = 1.0 if length_unit is None else si_factor(length_unit, 'length')

    with np.load(path, allow_pickle=True) as d:
        node = d['node']
        cs = d['coordinate_system']
        tl = d['traceline'] if 'traceline' in d else np.empty(0, TRACELINE_DTYPE)
        el = d['element'] if 'element' in d else np.empty(0, ELEMENT_DTYPE)

    raw = cs['matrix'].astype(np.float64)
    matrix = raw.copy()
    matrix[:, 3, :] *= scale  # origin row carries length

    # a node is written in the frame it is placed in, and reading those
    # numbers as global puts it somewhere else entirely (Brandon,
    # 2026-09-20). Resolved in the file's own units, because an angle
    # is not a length and the scale must not touch it.
    return Geometry(
        node_id=node['id'],
        node_xyz=to_global(node['coordinate'].astype(np.float64),
                           node['def_cs'], cs['id'], cs['cs_type'],
                           raw) * scale,
        node_def_cs=node['def_cs'],
        node_disp_cs=node['disp_cs'],
        node_color=node['color'],
        cs_id=cs['id'],
        cs_name=[str(n) for n in cs['name']],
        cs_type=cs['cs_type'],
        cs_matrix=matrix,
        traceline_id=tl['id'],
        traceline_color=tl['color'],
        traceline_desc=[str(s) for s in tl['description']],
        traceline_conn=[np.asarray(c) for c in tl['connectivity']],
        elem_id=el['id'],
        elem_type=el['type'],
        elem_color=el['color'],
        elem_conn=[np.asarray(c) for c in el['connectivity']],
        length_unit=length_unit,
    )

save ¶

save(geometry: Geometry, path: str | PathLike, unit_system: UnitSystem | None = None) -> None

Write a geometry in sdynpy's own .npz layout.

Coordinates go out in unit_system, or as stored without one. The format records no units either way, so whoever reads it has to be told — which is what "consistent units" means in this corner of the world.