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

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

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

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

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

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

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

```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) introduces the
package in four small steps:

1. [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. [Dataset generation](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 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

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