DynaResp

DynaResp generates synthetic structural-dynamics datasets with complete 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. The user keeps direct access to the physical matrices, modal properties, clean response, and sampled parameters.

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

dr.set_time_axis(np.arange(1000) / 100)
dr.set_position_axis(np.arange(3))

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

result = system.simulate(
    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),
        ),
    ],
    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

dr.set_time_axis(np.arange(600) / 200)
dr.set_position_axis(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,
)

result = beam.simulate(
    load=dr.loads.TwoWheelLoad(
        front_load=-4000,
        rear_load=-3500,
        speed=2.5,
        wheel_spacing=1.2,
    ),
    sensors=[dr.sensors.Accelerometer(position=2.5)],
)

Every load receives the same caller-supplied time and positions axes and returns a complete space-time field. Beam is the only beam model; it is uniform, simply supported, and assembled from bending elements. The solver performs its modal projection after the load field has been generated.

Generate a dataset

import numpy as np

import dynaresp as dr

dr.set_time_axis(np.arange(1000) / 100)
dr.set_position_axis(np.arange(3))


def build_system(trial: dr.Trial) -> dr.ShearBuilding:
    masses = [trial.suggest_float(f"mass_{floor}", 800, 1200) for floor in range(3)]
    stiffnesses = [
        trial.suggest_float(f"stiffness_{floor}", 5e5, 2e6, log=True)
        for floor in range(3)
    ]
    return dr.ShearBuilding(
        masses=masses,
        stiffnesses=stiffnesses,
        damping_ratio=trial.suggest_float("damping_ratio", 0.005, 0.03),
    )


def build_load(trial: dr.Trial) -> dr.loads.WhiteNoise:
    return dr.loads.WhiteNoise(
        position=0,
        rms=trial.suggest_float("load_rms", 5, 20, log=True),
    )


dataset = dr.generate_dataset(
    n_samples=10_000,
    system_builder=build_system,
    load_builder=build_load,
    sensors=[dr.sensors.Accelerometer(position=i) for i in range(3)],
    output="data/shear-building.zarr",
    seed=42,
    workers=4,
)

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.clean_signal)
print(sample.target)
print(sample.system["mass_matrix"])
print(sample.modal["frequencies_hz"])
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="stiffness_reduction",
    extras=["frequencies", "stiffness_matrix"],
)

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 four focused steps:

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

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 remains available.

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