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

from dynaresp import loads, sensors, systems

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

result = system.simulate(
    load=loads.WhiteNoise(dof=0, rms=10),
    sensors=[
        sensors.Accelerometer(position=0),
        sensors.Accelerometer(position=1),
        sensors.Accelerometer(
            position=2,
            noise=sensors.GaussianNoise(snr_db=30),
        ),
    ],
    duration=10,
    sampling_rate=100,
    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

from dynaresp import CantileverBeam, loads, sensors

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

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

All point-load classes use the same public API for MDOF systems and beams. Loads produce physical space-time histories; the solver performs beam shape function and modal projection internally.

The first continuous-system family includes CantileverBeam, SimplySupportedBeam, FixedFixedBeam, FixedPinnedBeam, and FreeFreeBeam.

Generate a dataset

from dynaresp import LogUniform, Uniform

dataset = system.generate_dataset(
    n_samples=10_000,
    vary={
        "masses": Uniform(800, 1200),
        "stiffnesses": LogUniform(5e5, 2e6),
        "damping_ratio": Uniform(0.005, 0.03),
        "load.rms": Uniform(5, 20),
    },
    load=loads.WhiteNoise(dof=0, rms=10),
    sensors=[sensors.Accelerometer(position=i) for i in range(3)],
    duration=10,
    sampling_rate=100,
    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.

Recipes are plain configuration data and can be reconstructed through the package factory:

from dynaresp import factory

config = dataset.metadata["recipe"]
restored_recipe = factory.create_recipe(config)

ComponentFactory keeps concrete construction in one place. Its public type registries can be extended by applications that provide compatible custom systems, loads, sensors, or measurement effects.

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"])

Beam damage is varied through damage.position and damage.severity. Damage is modeled as a local elemental bending-stiffness reduction and that assumption is stored in the recipe metadata.

Machine-learning views

torch_dataset = dataset.to_torch(
    inputs="signal",
    targets="damage_severity",
    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 introduces the package in four small steps:

1. Systems and modes
2. Loads in space and time
3. Simulation and sensors
4. Dataset generation

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 Euler--Bernoulli 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