visualdynamics 0.1.0a72__tar.gz → 0.1.0a73__tar.gz

{visualdynamics-0.1.0a72/src/visualdynamics.egg-info → visualdynamics-0.1.0a73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visualdynamics
-Version: 0.1.0a72
+Version: 0.1.0a73
 Summary: Structural Dynamics Visualization: a units-aware structural dynamics analysis toolset
 Author-email: Brandon Zwink <bzwink@gmail.com>
 License-Expression: MIT

{visualdynamics-0.1.0a72 → visualdynamics-0.1.0a73}/src/visualdynamics/__init__.py

@@ -97,7 +97,7 @@ from .units import (
 #: alpha, said in the version itself so the dialog, the About text, the
 #: installers and latest.json all say the same thing, and the first
 #: non-alpha release is offered as an upgrade (Brandon, 2026-09-11)
-__version__ = '0.1.0a72'
+__version__ = '0.1.0a73'
 
 
 def launch_gui(*paths: str, in_process: bool | None = None) -> Any:

{visualdynamics-0.1.0a72 → visualdynamics-0.1.0a73}/src/visualdynamics/compatibility.py

@@ -19,9 +19,12 @@ importing data before its geometry does not mark everything red.
 
 A data object whose DOFs are all modal coordinates (`M1` ... `Mn`, see
 `validate.modal_coordinate`) names no node. It answers to a shape set,
-the one it was transformed through, and fits wherever there is a set
-with at least as many modes as it names: a set in its object group when
-it is in one, any set in the project otherwise.
+the one it was transformed or computed through, and fits wherever there
+is a set with at least as many modes as it names: a set in its object
+group when it is in one, any set in the project otherwise. A time
+history can hold both kinds of record, forces with the modal responses
+computed from them appended: its physical records answer to the
+geometry and its modal records to the shape sets, each by its own rule.
 
 Not checked here:
 
@@ -51,9 +54,11 @@ MAX_LISTED = 6  # DOFs named in a message before it summarizes
 class Issue:
     """Why one object does not fit the geometry or shape set it answers to.
 
-    `kind` is 'dofs-not-in-geometry' or 'modes-not-in-set'. `missing_dofs`
-    lists the DOFs at fault, and `sub_items` the indices of the records,
-    shapes or channels that name them.
+    `kind` is 'dofs-not-in-geometry', 'modes-not-in-set' (an object of
+    modal coordinates alone), or 'modes-beyond-set' (modal records beside
+    physical ones, the physical ones fitting). `missing_dofs` lists the
+    DOFs at fault, and `sub_items` the indices of the records, shapes or
+    channels that name them.
     """
 
     name: str
@@ -169,28 +174,39 @@ def modal_object(obj: Any) -> int | None:
     return max(indices)
 
 
+def modal_records(obj: Any) -> list[int]:
+    """The records of a data object at modal coordinates; empty for
+    anything else."""
+    from .core.data import DataArray
+
+    if not isinstance(obj, DataArray):
+        return []
+    return [i for i, dof in enumerate(obj.response_dof) if _index(dof)]
+
+
 def check_modal(name: str, obj: Any, companions: Mapping[str, Any]
                 ) -> Issue | None:
     """The Issue for a modal object against the shape sets among its
     companions, or None when one of them has every mode it names.
 
     The Issue's kind is 'modes-not-in-set', and its `sub_items` are the
-    records that name a mode beyond the largest set.
+    records that name a mode beyond the largest set. A mixed object's
+    physical records name no mode and are never among them.
     """
     from .core.shapes import ShapeSet
 
-    highest = modal_object(obj)
+    records = range(obj.num_records)
+    highest = max(_index(obj.response_dof[i]) for i in records)
     sets = {other: value for other, value in companions.items()
             if isinstance(value, ShapeSet) and other != name}
     if any(value.num_shapes >= highest for value in sets.values()):
         return None
-    beyond = [i for i, dof in enumerate(obj.response_dof)
-              if _index(dof) > max((v.num_shapes for v in sets.values()),
-                                   default=0)]
+    beyond = [i for i in records
+              if _index(obj.response_dof[i])
+              > max((v.num_shapes for v in sets.values()), default=0)]
     if not sets:
         message = (f'modal coordinates up to M{highest}, and no shape set '
-                   'to answer to — link the set they were transformed '
-                   'through')
+                   'to answer to — link the set they belong to')
     else:
         most = max(sets.items(), key=lambda item: item[1].num_shapes)
         message = (f'modal coordinates up to M{highest}, but shape set '
@@ -219,7 +235,9 @@ def blocks_a_link(issue: Issue | None) -> bool:
 
     What blocks is a modal object with no shape set that has as many
     modes as it names, since it has nothing to be drawn against in any
-    geometry. (`Project.link` refuses two geometries in one group before
+    geometry. A time history holding modal records beside physical ones
+    does not block: its physical records are drawn, and the shortfall of
+    its modal ones is reported ('modes-beyond-set'). (`Project.link` refuses two geometries in one group before
     this is called.)
 
     Parameters
@@ -230,15 +248,15 @@ def blocks_a_link(issue: Issue | None) -> bool:
     Returns
     -------
     bool
-        True for a 'modes-not-in-set' issue, False for None or a
-        'dofs-not-in-geometry' issue.
+        True for a 'modes-not-in-set' issue, False for None or any
+        other kind.
     """
     # Missing nodes stopped blocking after a real report failed on them
     # twice in two days (Brandon, 2026-09-20 and 2026-09-21), the second
     # time on an object whose channels were all virtual. That is why the
     # first attempt, refusing only when nothing overlapped, was not a
     # line that could be drawn either.
-    return issue is not None and issue.kind != 'dofs-not-in-geometry'
+    return issue is not None and issue.kind == 'modes-not-in-set'
 
 
 def check_object(name: str, obj: Any, geometry: Geometry | None,
@@ -261,7 +279,8 @@ def check_object(name: str, obj: Any, geometry: Geometry | None,
         return None
     if modal_object(obj) is not None:
         return check_modal(name, obj, companions or {})
-    if geometry is None:
+    modal = modal_records(obj)
+    if geometry is None and not modal:
         return None
 
     if isinstance(obj, ShapeSet):
@@ -277,8 +296,14 @@ def check_object(name: str, obj: Any, geometry: Geometry | None,
             sub_items=list(range(obj.num_shapes)))
 
     if isinstance(obj, DataArray):
+        # modal records beside physical ones (Brandon, 2026-10-25: forces
+        # with their modal responses appended went red, every M record
+        # read as a node the geometry lacked): each kind by its own rule
+        skipped = set(modal)
         missing, flagged = [], []
         for i in range(obj.num_records):
+            if geometry is None or i in skipped:
+                continue
             dofs = [obj.response_dof[i]]
             if obj.reference_dof is not None:
                 dofs.append(obj.reference_dof[i])
@@ -286,14 +311,21 @@ def check_object(name: str, obj: Any, geometry: Geometry | None,
             if gone:
                 flagged.append(i)
                 missing.extend(d for d in gone if d not in missing)
-        if not flagged:
+        short = check_modal(name, obj, companions or {}) if modal else None
+        if not flagged and short is None:
             return None
-        return Issue(
-            name=name, kind='dofs-not-in-geometry',
-            message=(f'{len(flagged)} of {obj.num_records} records reference '
-                     f'DOFs not in geometry {geometry_name!r}: '
-                     f'{_listed(missing)}'),
-            missing_dofs=missing, sub_items=flagged)
+        said, kind = [], 'modes-beyond-set'
+        if flagged:
+            kind = 'dofs-not-in-geometry'
+            said.append(f'{len(flagged)} of {obj.num_records} records '
+                        f'reference DOFs not in geometry {geometry_name!r}: '
+                        f'{_listed(missing)}')
+        if short is not None:
+            said.append(short.message)
+            missing += short.missing_dofs
+            flagged = sorted(flagged + short.sub_items)
+        return Issue(name=name, kind=kind, message='; '.join(said),
+                     missing_dofs=missing, sub_items=flagged)
 
     if isinstance(obj, ChannelTable):
         dofs = obj.dof_strings()
@@ -374,11 +406,12 @@ def check_compatibility(objects: Mapping[str, Any],
     for name, obj in objects.items():
         if modal_object(obj) is not None:
             issue = check_modal(name, obj, companions(name))
-        elif geometry_name is None:
+        elif geometry_name is None and not modal_records(obj):
             continue
         else:
             against = home(name)
-            issue = check_object(name, obj, geometries.get(against), against)
+            issue = check_object(name, obj, geometries.get(against), against,
+                                 companions=companions(name))
         if issue is not None:
             report.issues[name] = issue
     return report

{visualdynamics-0.1.0a72 → visualdynamics-0.1.0a73}/src/visualdynamics/core/data.py

@@ -1333,8 +1333,10 @@ class TimeHistory(DataArray):
         **kwargs
             Passed to `visualdynamics.viz.animate.animate_time`:
             `quantity=` picks which measurement moves the geometry in a
-            mixed record (the most common one by default),
-            `screenshot=` saves a still at the sample with the largest
+            mixed record (the most common one by default), `shapes=` a
+            shape set plays the record's modal coordinates through its
+            mode shapes, `screenshot=` saves a still at the sample with
+            the largest
             deflection, `movie=` saves the record once through as an MP4,
             `seconds=` sets how long that takes.
 

visualdynamics-0.1.0a73/src/visualdynamics/core/modal_response.py

@@ -0,0 +1,298 @@
+"""Modal responses: how each mode of a model answers the forces a record
+holds, computed in modal coordinates and kept beside the forces.
+
+A model's modes are a compact description of how it moves: a large
+finite element model has many more physical DOFs than modes in a
+bandwidth, and the response anywhere follows from the modal responses
+by u = Φq. So the response to a test's forces is computed and kept as
+modal responses, one record per mode, appended to the time history the
+forces are in; the physical response at any DOF is a later expansion.
+
+The forces are made modal first, pᵣ = Σₖ φₖᵣ fₖ, the projection
+`transform.to_modal` makes of a force record (a record already holding
+modal forces is used as it is). Each mode r then answers its own
+equation,
+
+    q̈ᵣ + 2ζᵣωᵣ q̇ᵣ + ωᵣ² qᵣ = pᵣ(t) / mᵣ,
+
+with ωᵣ, ζᵣ and mᵣ the set's frequency, damping and modal mass (one for
+a mass-normalized set). It is solved exactly for a force that varies
+linearly between samples: the mode's state equation discretized with a
+first-order hold, which is a second-order recursive filter run over the
+record. Nothing else is approximated, so the start of a record, a
+transient, and a rigid-body mode (ωᵣ = 0, whose displacement under a
+net force grows without bound, as it does) are all answered as they are.
+The record starts at rest.
+
+The response is a displacement, a velocity or an acceleration of each
+modal coordinate, `M1` … `Mn` named as everywhere in the package (the
+mode's 1-based index in its set). Through a mass-normalized set the
+units carry a half power of mass, the `modal_*` dimensions, as
+`transform` gives them; through any other set they are left undeclared
+and hinted.
+
+References
+----------
+.. [1] G. F. Franklin, J. D. Powell and M. L. Workman, *Digital Control
+   of Dynamic Systems*, 3rd ed., Addison-Wesley, 1998, sec. 6.3.2
+   (the triangle-hold equivalent).
+.. [2] R. R. Craig and A. J. Kurdila, *Fundamentals of Structural
+   Dynamics*, 2nd ed., Wiley, 2006, ch. 10.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Sequence
+
+import numpy as np
+
+from ..units import UNKNOWN
+from .data import TimeHistory
+from .shapes import ShapeSet
+from .transform import MODAL, modal_dofs, reads_as, to_modal
+
+#: what each response is, by the name a user picks
+QUANTITIES: dict[str, str] = {'displacement': 'length',
+                              'velocity': 'velocity',
+                              'acceleration': 'acceleration'}
+
+#: the modal force dimension `transform` gives a mass-normalized set
+MODAL_FORCE = MODAL['force']
+
+
+def _mode_response(force: np.ndarray, frequency: float, damping: float,
+                   mass: float, dt: float, quantity: str) -> np.ndarray:
+    """A mode's response to its modal force, sampled every `dt` and
+    linear between samples, from rest.
+
+    The state x = (q, q̇) over one step with the force linear from u[k]
+    to u[k+1] is exactly x[k+1] = Φ x[k] + (Γa − Γb) u[k] + Γb u[k+1],
+    with Φ, Γa and Γb blocks of the exponential of the step's augmented
+    matrix. Written in w[k] = x[k] − Γb u[k], it is a causal state
+    equation, and so a second-order filter; at rest x[0] = 0 means
+    w[0] = −Γb u[0], whose decay C Φᵏ w[0] is added to the filter's
+    output, which starts from w[0] = 0.
+    """
+    # scipy's cont2discrete(method='foh') is the triangle-hold
+    # equivalent, which is centered: a rigid mode under a constant force
+    # came out half a sample early (3·dt·T/2 too far after T seconds),
+    # and a two-DOF model 0.37 % off a direct simulation (2026-10-25)
+    from scipy.linalg import expm
+    from scipy.signal import lfilter, ss2tf
+
+    w = 2.0 * np.pi * float(frequency)
+    z = float(damping)
+    a = np.array([[0.0, 1.0], [-w * w, -2.0 * z * w]])
+    b = np.array([[0.0], [1.0 / mass]])
+    if quantity == 'displacement':
+        c, d = np.array([[1.0, 0.0]]), np.array([[0.0]])
+    elif quantity == 'velocity':
+        c, d = np.array([[0.0, 1.0]]), np.array([[0.0]])
+    else:
+        c, d = np.array([[-w * w, -2.0 * z * w]]), np.array([[1.0 / mass]])
+    augmented = np.zeros((4, 4))
+    augmented[:2, :2] = a * dt
+    augmented[:2, 2:3] = b * dt
+    augmented[2, 3] = 1.0
+    blocks = expm(augmented)
+    phi, gamma_a, gamma_b = blocks[:2, :2], blocks[:2, 2:3], blocks[:2, 3:4]
+    num, den = ss2tf(phi, phi @ gamma_b + gamma_a - gamma_b, c,
+                     c @ gamma_b + d)
+    out = lfilter(np.real(num[0]), np.real(den), force)
+    if force.size and force[0] != 0.0:
+        # C Φᵏ Γb for k = 0, 1, …: the impulse response of (Φ, Γb, C),
+        # one sample on
+        num_0, den_0 = ss2tf(phi, gamma_b, c, np.zeros((1, 1)))
+        impulse = np.zeros(force.size + 1)
+        impulse[0] = 1.0
+        decay = lfilter(np.real(num_0[0]), np.real(den_0), impulse)[1:]
+        out -= force[0] * decay
+    return out
+
+
+def modal_forces(history: TimeHistory, shapes: ShapeSet,
+                 records: Sequence[int] | None = None) -> TimeHistory:
+    """The modal forces the record's force channels put on every mode of
+    the set, one record per mode, `M1` … `Mn`.
+
+    Force channels on DOFs the set covers are projected, pᵣ = Σ φₖᵣ fₖ;
+    a record whose channels are already the set's modal forces is used
+    as it is. Other channels (the responses) are passed over.
+
+    Raises
+    ------
+    ValueError
+        If no picked record is a force on a DOF the set covers, the set
+        is complex or has no modes.
+    """
+    if shapes.num_shapes == 0:
+        raise ValueError('the set has no modes')
+    if shapes.is_complex:
+        raise ValueError('the set is complex: a real force cannot drive a '
+                         'complex modal coordinate here')
+    picked = (list(range(history.num_records)) if records is None
+              else sorted({int(i) for i in records}))
+    names = set(modal_dofs(shapes))
+    modal = [i for i in picked if history.response_dof[i] in names
+             and history.ordinate_dim[i] in (MODAL_FORCE, 'force', UNKNOWN)
+             and (history.ordinate_dim[i] == MODAL_FORCE
+                  or history.dimension_hint[i] == MODAL_FORCE)]
+    if modal and reads_as(history, shapes) == 'modal':
+        rows = np.zeros((shapes.num_shapes, len(history.abscissa)))
+        order = modal_dofs(shapes)
+        for i in modal:
+            rows[order.index(history.response_dof[i])] += history.ordinate[i]
+        dim = history.ordinate_dim[modal[0]]
+        return TimeHistory(history.abscissa, rows, response_dof=order,
+                           ordinate_dim=dim,
+                           dimension_hint=None if dim != UNKNOWN else MODAL_FORCE)
+    forces = [i for i in picked if history.ordinate_dim[i] == 'force']
+    if not forces:
+        raise ValueError('no force channel picked: the modal response is '
+                         'the answer to forces, and the record holds none '
+                         'on the DOFs picked')
+    projected, _report = to_modal(history, shapes, records=forces)
+    return projected
+
+
+def modal_responses(history: TimeHistory, shapes: ShapeSet, *,
+                    modes: Sequence[int] | None = None,
+                    quantity: str = 'acceleration',
+                    records: Sequence[int] | None = None,
+                    label: str = 'shapes') -> TimeHistory:
+    """Each picked mode's response to the record's forces, one record per
+    mode, at the modal coordinates `M1` … `Mn`.
+
+    Parameters
+    ----------
+    history : TimeHistory
+        Evenly sampled, holding force channels on DOFs the set covers,
+        or the set's modal forces.
+    shapes : ShapeSet
+        Real modes with frequency, damping and modal mass.
+    modes : sequence of int, optional
+        Which modes, by index in the set from zero; every mode when
+        omitted.
+    quantity : str, default 'acceleration'
+        'displacement', 'velocity' or 'acceleration' of each modal
+        coordinate.
+    records : sequence of int, optional
+        Which of the history's records are the forces; every force
+        channel when omitted.
+    label : str, default 'shapes'
+        The set's name, written into each record's comment, which is how
+        a later run through the same set finds the records to replace.
+
+    Returns
+    -------
+    TimeHistory
+        One record per mode picked, on the history's own time axis.
+
+    Raises
+    ------
+    ValueError
+        If the quantity is not one of `QUANTITIES`, a mode is not in the
+        set, the record is not evenly sampled, or as `modal_forces`.
+    """
+    if quantity not in QUANTITIES:
+        raise ValueError(f'{quantity!r} is not a response: one of '
+                         f'{", ".join(QUANTITIES)}')
+    chosen = (list(range(shapes.num_shapes)) if modes is None
+              else sorted({int(k) for k in modes}))
+    bad = [k for k in chosen if not 0 <= k < shapes.num_shapes]
+    if bad:
+        raise ValueError(f'no mode {bad[0] + 1}: the set has '
+                         f'{shapes.num_shapes}')
+    if not chosen:
+        raise ValueError('no mode picked')
+    t = np.asarray(history.abscissa, dtype=float)
+    steps = np.diff(t)
+    if t.size < 2 or not np.allclose(steps, steps[0], rtol=1e-6, atol=0.0):
+        raise ValueError('the record is not evenly sampled')
+    dt = float(steps[0])
+    forces = modal_forces(history, shapes, records)
+    names = modal_dofs(shapes)
+    rows = np.empty((len(chosen), t.size))
+    for row, k in enumerate(chosen):
+        rows[row] = _mode_response(np.asarray(forces.ordinate[k], dtype=float),
+                                   shapes.frequency[k], shapes.damping[k],
+                                   float(shapes.modal_mass[k]), dt, quantity)
+    force_dim = forces.ordinate_dim[0]
+    physical = QUANTITIES[quantity]
+    known = force_dim == MODAL_FORCE
+    dim = MODAL[physical] if known else UNKNOWN
+    hint = None if known else MODAL[physical]
+    comments = [f'{label}: modal {quantity}, mode {k + 1} at '
+                f'{float(shapes.frequency[k]):.4g} Hz' for k in chosen]
+    return TimeHistory(t, rows, response_dof=[names[k] for k in chosen],
+                       ordinate_dim=dim, dimension_hint=hint,
+                       comment=comments)
+
+
+def made_through(history: TimeHistory, label: str) -> list[int]:
+    """The records of `history` that an earlier run through the set
+    named `label` appended (`modal_responses` writes the name into each
+    record's comment)."""
+    prefix = f'{label}: modal '
+    return [i for i, comment in enumerate(history.comment)
+            if comment.startswith(prefix)]
+
+
+def appended(history: TimeHistory, responses: TimeHistory,
+             label: str) -> TimeHistory:
+    """`history` with `responses` appended as records after its own, the
+    records an earlier run through the same set made taken out first.
+    Its averaging, shock windows, roles and other settings are kept;
+    `history` itself is not changed."""
+    keep = [i for i in range(history.num_records)
+            if i not in set(made_through(history, label))]
+    out = copy.copy(history)
+    n = len(responses.response_dof)
+
+    def joined(field: str, new: list) -> list | None:
+        old = getattr(history, field)
+        if old is None and all(v is None for v in new):
+            return None
+        old = [None] * history.num_records if old is None else list(old)
+        return [old[i] for i in keep] + list(new)
+
+    out.ordinate = np.vstack([np.asarray(history.ordinate)[keep],
+                              responses.ordinate])
+    out.response_dof = [history.response_dof[i] for i in keep] + list(
+        responses.response_dof)
+    out.ordinate_dim = [history.ordinate_dim[i] for i in keep] + list(
+        responses.ordinate_dim)
+    out.ordinate_unit = [history.ordinate_unit[i] for i in keep] + list(
+        responses.ordinate_unit)
+    out.reference_unit = [history.reference_unit[i] for i in keep] + list(
+        responses.reference_unit)
+    out.comment = [history.comment[i] for i in keep] + list(responses.comment)
+    out.dimension_hint = [history.dimension_hint[i] for i in keep] + list(
+        responses.dimension_hint)
+    out.reference_dof = joined('reference_dof', [None] * n)
+    # a history with no capture labels keeps none: blank labels would
+    # read as one capture named '' (2026-10-25)
+    out.block = (None if history.block is None
+                 else [b or '' for b in joined('block', [''] * n)])
+    return out
+
+
+#: the most samples a preview computes, so that it answers while the
+#: pane is open; Compute runs the whole record
+PREVIEW_SAMPLES = 2 ** 16
+
+
+def preview_responses(history: TimeHistory, shapes: ShapeSet, *,
+                      modes: Sequence[int] | None = None,
+                      quantity: str = 'acceleration',
+                      records: Sequence[int] | None = None,
+                      label: str = 'shapes') -> TimeHistory:
+    """`modal_responses` over the first `PREVIEW_SAMPLES` of the record:
+    the same responses there, since each starts from rest at the
+    record's start."""
+    short = copy.copy(history)
+    short.abscissa = np.asarray(history.abscissa)[:PREVIEW_SAMPLES]
+    short.ordinate = np.asarray(history.ordinate)[:, :PREVIEW_SAMPLES]
+    return modal_responses(short, shapes, modes=modes, quantity=quantity,
+                           records=records, label=label)