Timoshenko Engine

Reusable structural engineering building blocks for Python applications.

Timoshenko packages common structural calculations, modal analysis, sensor workflows, and monitoring components so applications can reuse them instead of rebuilding the same foundations for every project. It is an embeddable Python library, not a hosted monitoring service or a general finite-element solver.

Alpha: the API may still change between releases. Every behavior change is listed in the changelog.

Install

python -m pip install timoshenko-engine

The distribution is named timoshenko-engine; the import package is timoshenko. Optional MQTT support is an extra:

python -m pip install "timoshenko-engine[mqtt]"

Quick start

Compare measured vibration with a reference model. This example simulates a record in which both modes are 5% below the model:

import numpy as np
import timoshenko as tm

structure = tm.Structure(
    structure_id="building-01",
    story_masses_kg=[120_000.0, 110_000.0],
    story_stiffness_n_m=[85_000_000.0, 70_000_000.0],
)
print(structure.natural_frequencies_hz)          # (2.626, 6.476)

fs = 100.0
t = np.arange(60_000) / fs
f1, f2 = (0.95 * f for f in structure.natural_frequencies_hz)
signal = np.sin(2 * np.pi * f1 * t) + 0.4 * np.sin(2 * np.pi * f2 * t)
sensors = tm.SensorData(signal, sampling_hz=fs, unit="m/s^2")

result = tm.monitor(structure, sensors, review_threshold_pct=3.0)
print(result.structure.update_scale_factor)      # 0.903, since stiffness scales with frequency squared
for change in result.health.mode_changes:
    print(change.mode_number, change.change_pct)  # 1 -5.0, then 2 -5.0
print(result.health.review_recommended)          # True

Real records load from CSV or JSON with tm.load_sensors("acceleration.csv", sampling_hz=100.0, column="acc"). The steps inside tm.monitor are also available separately as tm.modal.identify, tm.update, and tm.health.assess. The review flag is raised only when you pass a threshold: a meaningful value depends on the structure and its environmental variability, so the engine does not choose one.

Engineering calculations

Closed-form functions take and return SI units and validate their inputs:

import timoshenko as tm

section = tm.rectangle_section(width_m=0.3, height_m=0.6)
beam = tm.simply_supported_uniform_load(
    20_000.0, 6.0, 30e9, section.second_moment_y_m4,
    shear_modulus_pa=12.5e9, area_m2=section.area_m2,
)
print(beam.bending_m, beam.shear_m)  # 2.083 mm bending, 0.048 mm shear

frequency = tm.propagate_uncertainty(
    tm.natural_frequency_hz,
    {"mass_kg": 250.0, "stiffness_n_m": 4e5},
    standard_uncertainties={"mass_kg": 5.0, "stiffness_n_m": 8e3},
)
print(frequency.estimate, frequency.standard_uncertainty)  # 6.366 Hz ± 0.090 Hz

What it provides

Sensor collection, alarm policy, and engineering interpretation remain with the application that embeds Timoshenko.

Multi-channel modal analysis

Frequency domain decomposition needs synchronized channels with a common sample rate and unit:

signals = tm.load_multichannel_csv(
    "aligned_accelerometers.csv",
    columns=["deck_left", "deck_center", "deck_right"],
    sampling_hz=100.0,
    units=["m/s^2"] * 3,
)
fdd = tm.identify_fdd(signals, nperseg=1024, max_modes=5)
for mode in fdd.modes:
    print(mode.frequency_hz, mode.shape_real)

Monitoring sessions

A host application feeds timestamped observation batches. The session aligns samples to the sample grid, waits for a fresh contiguous window after gaps, and analyzes every configured hop:

session = tm.MonitoringSession(
    structure,
    sensor_ids=["deck-left", "deck-right"],
    units=["m/s^2", "m/s^2"],
    sampling_hz=100.0,
    window_samples=2048,
    hop_samples=512,
    analysis_options={"nperseg": 512, "max_modes": 4},
    review_threshold_pct=5.0,
)
result = session.ingest(batch)  # batch: tm.ObservationBatch from your gateway or a source adapter
for report in result.reports:
    tm.report.save_html(report, "reports/latest.html")

The session does not open network connections or run in the background. Use tm.SessionRunner with a source such as tm.CSVObservationSource or tm.MqttObservationSource to drive it.

Documentation

The full documentation is at timoshenko.readthedocs.io. Good places to start:

• API reference
• Numerical methods and limits
• Architecture
• Monitoring sessions and source adapters
• Runnable examples, including a cross-check of PyNite shear-deformable beams
• Changelog

Limits and engineering posture

• Timoshenko is alpha software and is not a structural safety certification tool.
• The shear-building model is a small lumped-mass reference model, not a full FEM solver.
• Modal identification is a screening estimate. A single sensor may miss a mode near a modal node; unpaired peaks are reported rather than compared with the wrong mode.
• Damping is a coarse screening estimate, reported only when the averaged spectrum resolves the half-power bandwidth. FDD does not estimate damping.
• The model update applies a single stiffness scale. It cannot locate or size local damage.
• A frequency shift is evidence for human review, not a damage verdict. Temperature, sensor placement, boundary conditions, and other effects also shift measured frequencies.
• Closed-form mechanics and section functions rely on their documented ideal assumptions. They are not code-compliance checks.

Development

python -m pip install -e ".[test,lint]"
python -m pytest --cov
python -m ruff check .
python -m mypy

To preview the documentation site:

python -m pip install -e ".[docs]"
python -m mkdocs serve

Bug reports and pull requests are welcome in the issue tracker. See CONTRIBUTING.md for the checks a pull request needs to pass; issues labelled good first issue are small, self-contained starting points.

Citation

If you use Timoshenko in research, please cite it with its DOI, 10.5281/zenodo.22968739, which always resolves to the latest release; each release also has its own DOI on Zenodo. The metadata is in CITATION.cff, which GitHub's "Cite this repository" button reads.

License

Apache License 2.0. See LICENSE.