feat: named case-result load combinations with full GUI support

Snapshots the current development tree, headlined by proper load combinations (user request): a reusable LoadCombination entity of weighted completed static-case results (e.g. 1.2xDead + 1.6xLive). - core: LoadCombination/LoadCombinationItem entities, Project integration (lookup, unique ids, reference validation) - services: combinations.py (linear superposition + envelope), exported via services __init__ - commands: undoable Add/Delete/Update for combinations - GUI: Load Combinations manager dialog, Run-dialog evaluation, envelope display in Results panel, Combinations tab in Table dock - tests: unit coverage (validation, math, error paths) + integration superposition check vs a single factored run
2026-09-11 13:19:59 -04:00 · 2026-09-11 13:19:59 -04:00 · f361fee969
commit f361fee969
560 changed files with 178701 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,195 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="OTKO" width="640">
+</p>
+
+<p align="center">
+  A SAP2000-style desktop GUI for
+  <a href="https://openseespydoc.readthedocs.io/">OpenSeesPy</a>.
+  Draw the model, click run, look at the diagrams.
+</p>
+
+<p align="center">
+  <em>Pre-alpha. Under active development. APIs and file formats will change.</em>
+</p>
+
+---
+
+![OTKO main window](docs/screenshots/main_window.png)
+
+## Why
+
+OpenSees does nonlinear FEM well. Its user interface is a script.
+OTKO puts a visual front-end on it:
+
+- Draw nodes, frames, supports, and loads on a snapped grid.
+- Assign materials, sections, and load patterns through dialogs.
+- Run static, modal, pushover, and time-history analyses with progress
+  and cancel.
+- Look at the results — deformed shape, mode shapes, force
+  diagrams, pushover curves, time-history plots, hysteresis loops.
+- Save the model as one `.osmodel` JSON file. Diffs cleanly in Git,
+  builds cleanly from Python.
+
+Underneath, the `core` Pydantic model works fine from a script or
+notebook. The GUI is a front-end, not the whole product.
+
+## What works today
+
+- **Modeling** — grids, nodes, frames (elastic + force-based), trusses,
+  quads, zero-length sections, restraints, equalDOF constraints,
+  distributed loads, ground motions (`PathTimeSeries` /
+  `UniformExcitation`).
+- **Materials and sections** — `Steel01`, `Steel02`, `Concrete01`,
+  `Concrete02`, `ElasticPP`, `Hysteretic`, fiber sections (rectangular /
+  circular patches + rebar layers), `SectionAggregator`,
+  `BeamWithHinges`.
+- **Analyses** — static (load- or displacement-controlled), modal,
+  displacement-controlled 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
+  (in display units), time-history plots, hysteresis loops,
+  response-spectrum SRSS / CQC, snapshot + video export.
+- **Persistence** — one JSON `.osmodel` per project, Pydantic-validated,
+  round-trips clean.
+- **Examples** — 20+ verified examples, including OpenSees
+  Wiki Examples 1–4 and a fiber-section RC frame pushover.
+  See [`examples/README.md`](examples/README.md).
+
+## Tech stack
+
+| Layer        | Library                              |
+| ------------ | ------------------------------------ |
+| GUI          | PySide6 (Qt 6)                       |
+| 3D viewport  | PyVista + pyvistaqt (VTK)            |
+| 2D plots     | pyqtgraph                            |
+| Solver       | OpenSeesPy 3.8.0.0                   |
+| Numerics     | NumPy                                |
+| Storage      | Pydantic v2 (model), h5py (results)  |
+| Tests        | pytest, pytest-qt                    |
+| Lint / type  | ruff, mypy                           |
+
+## Architecture
+
+Strict MVVM + service layer. `core` is pure Python — no Qt,
+no OpenSeesPy imports — and unit-tests in isolation.
+
+```
+views (Qt)  →  viewmodels  →  services (OpenSeesRunner, Persistence)  →  core (model)
+```
+
+Long version in [`docs/architecture.md`](docs/architecture.md),
+including the OpenSeesPy command order the runner emits.
+
+## Documentation
+
+Practical, task-first walkthroughs live in
+[`docs/QUICK_GUIDE.md`](docs/QUICK_GUIDE.md) — a cantilever build,
+modal analysis, report/script export, display units, and undo/redo.
+The full index is [`docs/README.md`](docs/README.md).
+
+## Install (development)
+
+**Desktop GUI** (Qt, PyVista, pyqtgraph, imageio):
+
+```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]"
+```
+
+**Headless** (core + services only, no Qt):
+
+```bash
+pip install -e .
+```
+
+That pulls pydantic, numpy, h5py, openseespy and nothing else.
+Use it for scripts, notebooks, and web backends that reuse
+`otko.core` or `otko.services` without the GUI.
+
+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`.
+
+## Quick start
+
+```bash
+python -m otko
+```
+
+Then:
+
+1. **File → Open** → `examples/cantilever.osmodel`.
+2. **Analyze → Cases** → run `Tip-Load`.
+3. **Display → Show Force Diagram** → **M3**: linear moment,
+   50 kN·m at the fixed end. **V2**: constant -10 kN.
+4. **Display → Show Deformed Shape** → cantilever curve, as advertised.
+
+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.
+
+## Run the 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.
+
+## 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.
+
+## Collaborators wanted
+
+Most useful to people who already work with OpenSees and want a
+shorter path from idea to model — and would rather build it together
+than alone. Open an issue or say hi if you are:
+
+- A **structural / earthquake engineer** who knows OpenSees Tcl
+  or OpenSeesPy and can tell us when a feature is almost right
+  but not quite.
+- A **researcher** running pushover, IDA, or response-spectrum studies
+  who can check the GUI against hand-built scripts.
+- A **Python / Qt developer** into scientific desktop apps,
+  VTK rendering, or Pydantic schema design.
+- A **student** learning FEM and GUI architecture at the same time —
+  the examples and tests are meant to read as documentation.
+- A **UX / icon designer** willing to argue about dialogs, toolbar
+  icons, and visual language.
+
+Bug reports and reproducible test cases count as contributions.
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup and the rules
+enforced in review.
+
+## License
+
+OTKO is **GNU Affero General Public License v3.0**
+([`LICENSE`](LICENSE)). Read the license itself, not just this:
+
+- 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. closed-source commercial license), open an issue.
+
+Copyright © 2026 Ozan and contributors.