Metadata-Version: 2.5
Name: dynaresp
Version: 0.3.0
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

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

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

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

```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 four 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)

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