otko/README.md

<p align="center">
  <img src="docs/logo.svg" alt="OTKO" width="600">
</p>

<h3 align="center">Draw the model. Click run. Read the diagrams.</h3>

<p align="center">
  <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue"></a>
  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue">
  <img alt="Status: pre-alpha" src="https://img.shields.io/badge/status-pre--alpha-orange">
</p>

<p align="center">
  <em>Pre-alpha. Under active development. APIs and file formats will change.</em>
</p>

---

<table align="center">
  <tr>
    <td><img src="docs/screenshots/menu.png" alt="SAP2000-style cascading menus"></td>
    <td><img src="docs/screenshots/toolbar.png" alt="Compact dark toolbar"></td>
    <td><img src="docs/screenshots/grid.png" alt="Parametric grid generation"></td>
  </tr>
  <tr>
    <td align="center"><sub>SAP2000-style menus</sub></td>
    <td align="center"><sub>Compact dark toolbar</sub></td>
    <td align="center"><sub>Parametric grid wizard</sub></td>
  </tr>
</table>

## What is OTKO?

OpenSees does nonlinear FEM well. Its user interface is a script.
OTKO puts a visual front-end on top of it: draw nodes, frames,
supports, and loads on a snapped grid; assign materials, sections,
and load patterns through dialogs; run the analysis with progress
and cancel; then read the results — deformed shapes, mode shapes,
force diagrams, pushover curves, hysteresis loops.

Underneath, the `core` Pydantic model works fine from a script or
notebook without any GUI. The GUI is a front-end, not the whole
product.

## Highlights

| Area | What you get |
| ---- | ------------ |
| **Modeling** | Grid wizards, nodes, frames (elastic + force-based), trusses, quads, zero-length sections, restraints, equalDOF constraints, distributed loads, ground motions (`PathTimeSeries` / `UniformExcitation`). |
| **Materials &amp; sections** | `Steel01`, `Steel02`, `Concrete01`, `Concrete02`, `ElasticPP`, `Hysteretic`, fiber sections (rectangular / circular patches + rebar), `SectionAggregator`, `BeamWithHinges`. |
| **Analysis** | Static (load- or displacement-controlled), modal, pushover, transient time-history with mode-1 Rayleigh damping. Chained workflows: gravity preload → `loadConst -time 0.0` → pushover or transient. |
| **Post-processing** | Deformed shape with scale slider, animated mode shapes, axial / shear / moment diagrams, pushover curves, time-history plots, hysteresis loops, response-spectrum SRSS / CQC, snapshot + video export. |
| **Persistence** | One Pydantic-validated `.osmodel` JSON per project — diffs cleanly in Git, builds cleanly from Python. Analysis output in HDF5 (`*.osresults.h5`). |

20+ verified examples ship with the repo, including OpenSees Wiki
Examples 1–4 and a fiber-section RC frame pushover. See
[`examples/README.md`](examples/README.md).

## Quick start

```bash
git clone ssh://git@smill-home.ddns.net/smill/otko.git
cd otko

python -m venv .venv
.venv\Scripts\activate              # Windows
source .venv/bin/activate           # Linux / macOS

pip install -e ".[gui,dev]"         # desktop: Qt + PyVista + dev tools
# pip install -e .                  # headless: core + services only

python -m otko
```

Then:

1. **File → Open** → `examples/cantilever.osmodel`.
2. **Analyze → Cases** → run `Tip-Load`.
3. **Display → Show Force Diagram** → **M3**: 50 kN·m at the fixed end.
   **V2**: constant −10 kN.
4. **Display → Show Deformed Shape** → the cantilever curve.

Nonlinear version: open `examples/portal_pushover.osmodel`, run
`Push-X`, **Display → Show Pushover Curve** — elastic ramp, then a
yield plateau as the base hinges form.

Python 3.10+. On Windows use **3.12+** — `openseespywin==3.8.0.0`
has no 3.11 wheel (`Requires-Python >=3.12`). Both pins already
live in `pyproject.toml`.

## Architecture

Strict MVVM + service layer, one direction only:

```
views (Qt)  →  viewmodels  →  services (OpenSeesRunner, Persistence)  →  core (model)
```

`core` is pure Python — no Qt, no OpenSeesPy imports — and unit-tests
in isolation. PySide6 + PyVista on the view, pyqtgraph for 2D plots,
Pydantic v2 for the model, h5py for results. Long version, including
the OpenSeesPy command order the runner emits, in
[`docs/architecture.md`](docs/architecture.md).

## Roadmap

[`docs/roadmap.md`](docs/roadmap.md) has the phase-by-phase plan.
Phases 0–7 (modeling, analysis, post-processing) are mostly done.
Phase 8 — isolators, ground-motion library, IDA, fiber-section
editor polish — is where the open work is.

## Contributing

Collaborators welcome — most useful to people who already work with
OpenSees and want a shorter path from idea to model:

- **Structural / earthquake engineers** who can tell us when a feature
  is almost right but not quite.
- **Researchers** running pushover, IDA, or response-spectrum studies
  against hand-built scripts.
- **Python / Qt developers** into scientific desktop apps, VTK
  rendering, or Pydantic schema design.
- **Students** learning FEM and GUI architecture — the examples and
  tests are meant to read as documentation.
- **UX / icon designers** willing to argue about dialogs and toolbars.

Bug reports and reproducible test cases count as contributions. Setup
and the rules enforced in review: [`CONTRIBUTING.md`](CONTRIBUTING.md).

Test suite:

```bash
pytest tests/unit          # pure logic, milliseconds
pytest tests/gui           # Qt event-loop tests (pytest-qt)
pytest tests/integration   # real OpenSeesPy runs on bundled examples
```

CI runs lint + the non-`slow` subset on Linux / macOS / Windows
× Python 3.10 / 3.11 / 3.12.

## License

OTKO is **GNU Affero General Public License v3.0**
([`LICENSE`](LICENSE)). In short:

- Research, education, personal projects: fine, keep the copyright
  notice.
- Fork and modify: fine.
- Distribute it (modified or not): release your full source under
  AGPL-3.0.
- Run a modified version as a network service: release your
  modifications under AGPL-3.0.

Commercial forks stay open. If you need a different arrangement
(e.g. a closed-source commercial license), open an issue.

Copyright © 2026 Ozan and contributors.