Metadata-Version: 2.5
Name: dynaresp
Version: 0.4.1
Summary: Structural-dynamics simulation and synthetic-data generation
Project-URL: Homepage, https://github.com/YacineBelHadj/DynaResp
Project-URL: Documentation, https://yacinebelhadj.github.io/DynaResp/
Project-URL: Repository, https://github.com/YacineBelHadj/DynaResp
Project-URL: Issues, https://github.com/YacineBelHadj/DynaResp/issues
Project-URL: Changelog, https://github.com/YacineBelHadj/DynaResp/blob/main/CHANGELOG.md
Author: Yacine Bel-Hadj
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: Beam,Environmental and Operational Conditions,MDOF,Simulation,Structural dynamics,Synthetic data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.14,>=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.12
Requires-Dist: zarr>=3.1
Provides-Extra: analysis
Requires-Dist: pandas>=2.2; extra == 'analysis'
Requires-Dist: xarray>=2024.1; extra == 'analysis'
Provides-Extra: torch
Requires-Dist: torch>=2.3; extra == 'torch'
Description-Content-Type: text/markdown

# DynaResp

[![PyPI](https://img.shields.io/pypi/v/dynaresp.svg)](https://pypi.org/project/dynaresp/)
[![Python](https://img.shields.io/pypi/pyversions/dynaresp.svg)](https://pypi.org/project/dynaresp/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://yacinebelhadj.github.io/DynaResp/)
[![License](https://img.shields.io/pypi/l/dynaresp.svg)](LICENSE)

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

```text
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.

```bash
pip install dynaresp
```

Pandas and xarray integrations are optional:

```bash
pip install "dynaresp[analysis]"
```

PyTorch integration is installed separately because PyTorch is large:

```bash
pip install "dynaresp[torch]"
```

## One simulation

```python
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

```python
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

```python
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,
    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:

```python
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,
    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 and into
`sample.target`.

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`.

```python
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:

```python
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

```python
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:

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

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

```bash
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](examples/notebooks/README.md) exercises the
public workflow in five focused steps:

1. [Structural systems and modes](examples/notebooks/01_systems_and_modes.ipynb)
2. [Loads in space and time](examples/notebooks/02_loads.ipynb)
3. [Simulation and sensors](examples/notebooks/03_simulation_and_sensors.ipynb)
4. [Reproducible datasets and adapters](examples/notebooks/04_datasets.ipynb)
5. [EOV and structural population](examples/notebooks/05_beam_population.ipynb)

```bash
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

```bash
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
```
