157 lines
6.1 KiB
Markdown
157 lines
6.1 KiB
Markdown
<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 & 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.
|