DynaResp

DynaResp generates synthetic structural-dynamics datasets with explicitly selected measurements and physical ground truth. Its high-level workflow is deliberately small:

system + load + sensors -> simulation -> dataset -> Zarr / PyTorch / xarray

The package handles matrix assembly, beam discretization, modal projection, time integration, measurement effects, deterministic sampling, and incremental storage. A simulation still computes the complete physical result; dataset generation retains only the fields the user selects.

Install

DynaResp supports Python 3.11 through 3.13.

pip install dynaresp

Pandas and xarray integrations are optional:

pip install "dynaresp[analysis]"

PyTorch integration is installed separately because PyTorch is large:

pip install "dynaresp[torch]"

One simulation

import numpy as np

import dynaresp as dr

time = np.arange(1000) / 100
positions = np.arange(3)

system = dr.systems.ShearBuilding(
    masses=[1000, 900, 800],
    stiffnesses=[1e6, 8e5, 6e5],
    damping_ratio=0.02,
)

spec = dr.SimulationSpec(
    system=system,
    load=dr.loads.WhiteNoise(position=0, rms=10),
    sensors=(
        dr.sensors.Accelerometer(position=0),
        dr.sensors.Accelerometer(position=1),
        dr.sensors.Accelerometer(
            position=2,
            noise=dr.sensors.GaussianNoise(snr_db=30),
        ),
    ),
    time=time,
    positions=positions,
)
result = dr.run_simulation(spec, seed=42)

print(result.signal.shape)  # (3, 1000)
print(result.clean_signal.shape)  # (3, 1000)
print(result.mass_matrix)
print(result.frequencies)
print(result.mode_shapes)

MDOF sensor positions are integer DOF indices. Beam sensor positions are physical coordinates along the span.

Beams and moving loads

import numpy as np

import dynaresp as dr

time = np.arange(600) / 200
positions = np.linspace(0, 5, 101)

beam = dr.Beam(
    length=5,
    material="steel",
    section=("rectangular", 0.1, 0.02),
    damping_ratio=0.01,
    n_modes=6,
)

spec = dr.SimulationSpec(
    system=beam,
    load=dr.loads.TwoWheelLoad(
        front_load=-4000,
        rear_load=-3500,
        speed=2.5,
        wheel_spacing=1.2,
    ),
    sensors=(dr.sensors.Accelerometer(position=2.5),),
    time=time,
    positions=positions,
)
result = dr.run_simulation(spec)

Every load receives caller-supplied axes. Point and moving forces retain their exact physical coordinates during projection; load_values remains a nearest-grid diagnostic representation. Beam is uniform, simply supported, and assembled from bending elements.

Generate a dataset

import numpy as np

import dynaresp as dr

time = np.arange(1000) / 100
positions = np.arange(3)


def build_case(rng):
    return {
        "masses": rng.uniform(800, 1200, size=3),
        "stiffnesses": np.exp(rng.uniform(np.log(5e5), np.log(2e6), size=3)),
        "damping_ratio": rng.uniform(0.005, 0.03),
        "load_rms": np.exp(rng.uniform(np.log(5), np.log(20))),
    }


def build_system(case):
    return dr.ShearBuilding(
        masses=np.asarray(case["masses"], dtype=float),
        stiffnesses=np.asarray(case["stiffnesses"], dtype=float),
        damping_ratio=float(case["damping_ratio"]),
    )


def build_load(case):
    return dr.loads.WhiteNoise(
        position=0,
        rms=float(case["load_rms"]),
    )


dataset = dr.generate_dataset(
    n_samples=10_000,
    case_builder=build_case,
    system_builder=build_system,
    load_builder=build_load,
    sensors=[dr.sensors.Accelerometer(position=i) for i in range(3)],
    time=time,
    positions=positions,
    record=[
        dr.Record.signal,
        dr.Record.modal_parameter.frequencies_hz,
        dr.Record.case_parameter,
        dr.Record.time,
        dr.Record.positions,
        dr.Record.metadata.seed,
        dr.Record.metadata.generation,
    ],
    storage_dtype=np.float32,
    output="data/shear-building.zarr",
    seed=42,
    workers=4,
)

Controlled variability

Use exact cases when the study is an experimental design rather than a random distribution:

cases = dr.parameter_grid(
    mass_scale=[0.9, 1.0, 1.1],
    stiffness_scale=[0.8, 1.0, 1.2],
)


def controlled_system(case):
    mass_scale = float(case["mass_scale"])
    stiffness_scale = float(case["stiffness_scale"])
    return dr.ShearBuilding(
        masses=np.array([1000, 900, 800]) * mass_scale,
        stiffnesses=np.array([1e6, 8e5, 6e5]) * stiffness_scale,
    )


dataset = dr.generate_dataset(
    cases=cases,
    system_builder=controlled_system,
    load_builder=lambda _case: dr.loads.Harmonic(
        position=0,
        amplitude=10,
        frequency=2,
    ),
    sensors=[dr.sensors.Accelerometer(position=i) for i in range(3)],
    time=time,
    positions=positions,
    record=[
        dr.Record.signal,
        dr.Record.case_parameter,
    ],
    seed=42,
)

cases may also be an ordinary list of mappings for paired, conditional, or otherwise coupled values. n_samples is inferred from the cases. For random or correlated populations, pass case_builder(rng), which returns one mapping per sample using DynaResp's deterministic NumPy generator. cases and case_builder are mutually exclusive; case_builder requires n_samples. The system and load builders receive the same mutable dictionary in that order, so either can append numeric derived values that flow to later stages. Selecting Record.case_parameter stores those final values once and exposes them through sample.target.

record is required and accepts typed leaf fields from Record. The family objects organize related leaves; for example, select Record.modal_parameter.frequencies_hz, not Record.modal_parameter. The simulation runs in its normal float64 pipeline, then the selected floating arrays are cast to storage_dtype at the recording boundary. Integer case values use lossless int64 storage, and metadata/seed remains uint64.

When output is provided, samples are written incrementally to Zarr and are not accumulated in RAM. Every sample seed is derived only from the dataset seed and sample index, so generated values are identical for workers=1 and workers=16.

from dynaresp import StructuralDataset

dataset = StructuralDataset.open("data/shear-building.zarr")
sample = dataset[172]

print(sample.signal)
print(sample.target)
print(sample.modal["frequencies_hz"])
print(sample.time)
print(sample.metadata["seed"])

Local damage is defined directly on the beam by mapping zero-based element indices to fractional stiffness reductions:

damaged = dr.Beam(
    length=5,
    material="steel",
    section=("rectangular", 0.1, 0.02),
    n_elements=20,
    n_modes=6,
    stiffness_reductions={8: 0.25},
)

Machine-learning views

torch_dataset = dataset.to_torch(
    inputs="signal",
    targets="damping_ratio",
    extras=["frequencies"],
)

xarray_dataset = dataset.to_xarray()
properties = dataset.properties()

The views remain sample-indexed; the PyTorch adapter does not load the complete Zarr dataset into memory.

Documentation and notebook

The normal documentation and executable notebook are built together:

uv sync --group docs
uv run --group docs mkdocs serve

Open http://127.0.0.1:8000/. A strict static build is:

uv run --group docs mkdocs build --strict

The generated site/ directory is deployable to GitHub Pages. The included Pages workflow builds both Markdown pages and the notebook online.

Tutorial notebooks

The notebook tutorial series exercises the public workflow in five focused steps:

1. Structural systems and modes
2. Loads in space and time
3. Simulation and sensors
4. Reproducible datasets and adapters
5. EOV and structural population

uv sync --group notebooks

Open the notebooks with VS Code, JupyterLab, or another notebook client using the repository's .venv Python environment. Each notebook is independent, uses fixed random seeds, and runs from top to bottom.

Physical scope

• Inputs use a consistent unit system; DynaResp does not perform unit conversion.
• Dynamics are linear and time invariant within one sample.
• Beams use two-node bending elements followed by modal reduction.
• Moving wheels are prescribed forces, not coupled vehicle--bridge interaction.
• Runner contacts are a deliberately idealized sequence of half-sine impulses.
• Sensor effects alter measurements only; clean_signal can be recorded when the noise-free measurement is needed.

Development

uv sync --group dev --group docs
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest --cov=dynaresp
uv run mkdocs build --strict