smill/otko
Watch
1
0
Fork
You've already forked otko
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rewrite READMEs dry and blunt, rename Studio to OTKO
Some checks failed
CI / lint (pull_request) Has been cancelled
Details
CI / test (macos-latest, 3.10) (pull_request) Has been cancelled
Details
CI / test (macos-latest, 3.11) (pull_request) Has been cancelled
Details
CI / test (macos-latest, 3.12) (pull_request) Has been cancelled
Details
CI / test (ubuntu-latest, 3.10) (pull_request) Has been cancelled
Details
CI / test (ubuntu-latest, 3.11) (pull_request) Has been cancelled
Details
CI / test (ubuntu-latest, 3.12) (pull_request) Has been cancelled
Details
CI / test (windows-latest, 3.10) (pull_request) Has been cancelled
Details
CI / test (windows-latest, 3.11) (pull_request) Has been cancelled
Details
CI / test (windows-latest, 3.12) (pull_request) Has been cancelled
Details

Browse source
This commit is contained in:
smillmorel 2026-09-08 02:41:03 -04:00
commit 3d809ca301
11 changed files with 233 additions and 263 deletions
Download patch file Download diff file Expand all files Collapse all files

218
examples/README.md
View file

@ -1,34 +1,34 @@
# Example models
Pre-built `.osmodel` files plus the Python scripts that produce them.
Each model is set up with whichever case types the post-processing
features need, so you can exercise the full GUI without manually
defining materials, sections, loads, and analysis cases.
Pre-built `.osmodel` files plus the Python scripts that generate them.
Each one carries the case types the post-processing views need, so you
can exercise the GUI without defining materials, sections, loads, and
cases by hand.
## Files
| Model | Nodes | Elements | Cases | Best for demonstrating |
| Model | Nodes | Elements | Cases | Shows |
|---|---|---|---|---|
| `cantilever.osmodel` | 6 | 5 | Static × 2, Modal | Point & distributed loads, force diagrams, deformed shape, mode shapes |
| `portal_frame.osmodel` | 4 | 3 | Static, Modal, Transient | All Display features, simplest 3D |
| `space_frame_3d.osmodel` | 12 | 16 | Static, Modal, Transient (5% damping) | Realistic 3D rendering, multiple modes, damped EQ time-history |
| `cantilever.osmodel` | 6 | 5 | Static × 2, Modal | Point + distributed loads, force diagrams, deformed shape, mode shapes |
| `portal_frame.osmodel` | 4 | 3 | Static, Modal, Transient | All Display features, smallest 3D |
| `space_frame_3d.osmodel` | 12 | 16 | Static, Modal, Transient (5% damping) | 3D rendering, multiple modes, damped EQ time-history |
| `sdof_pushover.osmodel` | 2 | 1 | Pushover, Modal | Monotonic pushover curve, HystereticMaterial |
| `portal_pushover.osmodel` | 4 | 3 | Pushover, Modal | Fiber sections, BeamWithHinges, nonlinear pushover with yielding |
| `ex1a_canti2d.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Original OpenSees Ex 1a with shared gravity, push, and earthquake cases |
| `ex1b_portal2d.osmodel` | 4 | 3 | Static preload, Pushover, Transient EQ | Original OpenSees Ex 1b elastic portal frame with distributed gravity |
| `ex2a_canti2d_elastic_element.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Variable-driven cantilever example with derived parameters |
| `ex2b_canti2d_inelastic_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | First nonlinear cantilever with aggregated uniaxial section |
| `ex2c_canti2d_inelastic_fiber_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Fiber-section cantilever with coupled axial-flexural nonlinearity |
| `ex3_canti2d_elastic_element.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Example 3 elastic build with unit-scaled parameters |
| `ex3_canti2d_inelastic_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Example 3 aggregated-section nonlinear build |
| `ex3_canti2d_inelastic_fiber_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Example 3 fiber-section nonlinear build |
| `ex4_portal2d_elastic_element.osmodel` | 4 | 3 | Static preload, Pushover, Transient sine | Example 4 elastic portal frame with separated build/analysis workflow |
| `ex4_portal2d_inelastic_section.osmodel` | 4 | 3 | Static preload, Pushover, Transient sine | Example 4 aggregated-section portal frame variant |
| `ex4_portal2d_inelastic_fiber_section.osmodel` | 4 | 3 | Static preload, Pushover, Transient sine | Example 4 fiber-section portal frame variant |
| `ex1a_canti2d_eq.osmodel` | 2 | 1 | Static preload, Transient EQ | OpenSees Ex 1a style gravity + base excitation workflow |
| `eigen_two_storey_shear_frame.osmodel` | 6 | 6 | Modal | equalDOF floor constraints, mode shapes, eigenvalue workflow |
| `eigen_two_storey_one_bay_frame.osmodel` | 6 | 6 | Modal | classic elastic frame modal example, sway mode shapes |
| `concrete04_cantilever.osmodel` | 2 | 1 | Static (gravity), Pushover | Popovics Concrete04 fiber section; proof-of-concept for the Concrete04 end-to-end stack |
| `portal_pushover.osmodel` | 4 | 3 | Pushover, Modal | Fiber sections, BeamWithHinges, yielding pushover |
| `ex1a_canti2d.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | OpenSees Ex 1a, shared gravity + push + quake |
| `ex1b_portal2d.osmodel` | 4 | 3 | Static preload, Pushover, Transient EQ | OpenSees Ex 1b elastic portal, distributed gravity |
| `ex2a_canti2d_elastic_element.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Ex 2a cantilever, dimensions as named parameters |
| `ex2b_canti2d_inelastic_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Ex 2b, aggregated axial+flexure section |
| `ex2c_canti2d_inelastic_fiber_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Ex 2c, fiber section, coupled axial-flexure |
| `ex3_canti2d_elastic_element.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Ex 3 elastic build, unit-scaled parameters |
| `ex3_canti2d_inelastic_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Ex 3 aggregated-section build |
| `ex3_canti2d_inelastic_fiber_section.osmodel` | 2 | 1 | Static preload, Pushover, Transient EQ | Ex 3 fiber-section build |
| `ex4_portal2d_elastic_element.osmodel` | 4 | 3 | Static preload, Pushover, Transient sine | Ex 4 elastic portal, build/analysis split |
| `ex4_portal2d_inelastic_section.osmodel` | 4 | 3 | Static preload, Pushover, Transient sine | Ex 4 aggregated-section portal |
| `ex4_portal2d_inelastic_fiber_section.osmodel` | 4 | 3 | Static preload, Pushover, Transient sine | Ex 4 fiber-section portal |
| `ex1a_canti2d_eq.osmodel` | 2 | 1 | Static preload, Transient EQ | Ex 1a gravity + base excitation only |
| `eigen_two_storey_shear_frame.osmodel` | 6 | 6 | Modal | equalDOF floor constraints, shear-frame modes |
| `eigen_two_storey_one_bay_frame.osmodel` | 6 | 6 | Modal | Chopra 10.5 frame, sway modes, no constraints |
| `concrete04_cantilever.osmodel` | 2 | 1 | Static (gravity), Pushover | Concrete04 fiber section end-to-end |
## Quick tour
@ -38,37 +38,36 @@ File → Open → cantilever.osmodel
Analyze → Cases → run "Tip-Load"
Display → Show Force Diagram → component "M3" → linear moment, max at fixed end (50 kN·m)
→ component "V2" → constant -10 kN along the whole span
→ component "N" → ~zero (no axial load applied)
→ component "N" → ~zero (no axial load)
→ component "T" → ~zero (no torsion → console hint, no diagram)
Display → Show Deformed Shape → classic cantilever curve
Display → Show Deformed Shape → cantilever curve
```
The load is applied along the global Y axis (perpendicular to the beam,
in the horizontal plane). With the default 3D vertical-reference
convention this gives V2 / M3 — i.e. the "in-plane bending" pair.
Load runs along global Y (perpendicular to the beam, horizontal plane).
With the default 3D vertical-reference convention that lands on the
V2 / M3 pair — the in-plane bending pair.
**Distributed load (UDL) variant** — run the second case to see a
parabolic moment diagram:
UDL variant, parabolic moment:
```
Analyze → Cases → run "Uniform-Load"
Display → Show Force Diagram → M3 → parabolic, max 25 kN·m at fixed end
→ V2 → linear, max 10 kN at fixed end
```
### 2. Mode shapes — `portal_frame.osmodel` or `space_frame_3d.osmodel`
### 2. Mode shapes — `space_frame_3d.osmodel`
```
File → Open → space_frame_3d.osmodel
Analyze → Cases → run "Modal-6"
Display → Animate Mode Shape → mode 1 = X-sway, mode 2 = Y-sway
→ ▶ Play, scrub timeline, change scale
→ Play, scrub timeline, change scale
```
### 3. Time-history & hysteresis — `portal_frame.osmodel` or `space_frame_3d.osmodel`
### 3. Time-history and hysteresis — `space_frame_3d.osmodel`
```
File → Open → space_frame_3d.osmodel
Analyze → Cases → run "EQ-4s" (~5-10 sec on a modern laptop)
Display → Time-History Plot
- Node 12 (roof corner) + DOF 1 (X displacement) → "Add trace"
- Node 9 + DOF 1 → another trace, compare phase
- Node 9 + DOF 1 → second trace, compare phase
Display → Hysteresis Plot
- X = Node 12 / DOF 1, Y = Node 12 / DOF 3 → orbit
```
@ -78,137 +77,129 @@ Display → Hysteresis Plot
File → Open → sdof_pushover.osmodel
Analyze → Cases → run "Push-X"
Display → Show Pushover Curve
→ linear segment from origin, then softens through yield
→ linear from origin, then softens through yield
```
Note: this demo keeps the column elastic (proper nonlinear hinges require
BeamWithHingesElement with fibre sections — infrastructure is in place,
fibre-section editor is future work).
Column stays elastic here. Real nonlinear hinges need
BeamWithHinges + fiber sections; the machinery exists, the
fiber-section editor is still rough.
### 5. Nonlinear pushover with fiber hinges — `portal_pushover.osmodel`
```
File → Open → portal_pushover.osmodel
Analyze → Cases → run "Push-X"
Display → Show Pushover Curve
→ initial linear stiffness, then yield plateau as base hinges form
→ peak base shear corresponds to concrete crushing + rebar yield
→ linear stiffness, then yield plateau as base hinges form
→ peak base shear = concrete crushing + rebar yield
```
The columns use BeamWithHingesElements with FiberSections (concrete core
+ rebar layers) wrapped in a SectionAggregator (torsion spring).
Columns are BeamWithHinges + FiberSections (concrete core, rebar
layers) wrapped in a SectionAggregator for torsion.
### 6. Gravity + time-history chain — `ex1a_canti2d_eq.osmodel`
```bash
```
File → Open → ex1a_canti2d_eq.osmodel
Analyze → Cases → run "Earthquake"
Display → Time-History Plot
- Node 2 + DOF 1 (Ux) → horizontal response of the cantilever tip
- Node 2 + DOF 2 (Uy) → verify gravity stays essentially locked
- Node 2 + DOF 1 (Ux) → tip horizontal response
- Node 2 + DOF 2 (Uy) → gravity should stay locked
```
This model is intentionally tiny but important for workflow coverage:
it demonstrates the general transient recipe of
`Static preload → loadConst reset → UniformExcitation transient`
using a real ground-motion record imported into a `PathTimeSeries`.
Tiny model, exists for one reason: the standard transient recipe
`static preload → loadConst reset → UniformExcitation transient`
against a real ground-motion record in a `PathTimeSeries`.
### 7. Original OpenSees Ex 1a bundle — `ex1a_canti2d.osmodel`
```bash
### 7. OpenSees Ex 1a bundle — `ex1a_canti2d.osmodel`
```
File → Open → ex1a_canti2d.osmodel
Analyze → Cases → run "Push" or "Earthquake"
Display → Show Pushover Curve / Time-History Plot
```
This is the original cantilever-column Example 1a packaged as one model
with a shared gravity preload plus both lateral load variants. It is a
good small benchmark for checking that pushover and transient workflows
behave consistently on the same geometry.
Cantilever column with shared gravity preload and both lateral
variants. Small benchmark for checking pushover and transient agree
on the same geometry.
### 8. Original OpenSees Ex 1b bundle — `ex1b_portal2d.osmodel`
```bash
### 8. OpenSees Ex 1b bundle — `ex1b_portal2d.osmodel`
```
File → Open → ex1b_portal2d.osmodel
Analyze → Cases → run "Push" or "Earthquake"
Display → Show Pushover Curve / Time-History Plot
```
This is the original elastic portal-frame Example 1b bundled as one
project. It is especially useful because the gravity preload is carried
by a distributed beam load instead of nodal loads only.
Elastic portal frame. Gravity comes from a distributed beam load
instead of nodal loads, which is the whole point of keeping it
around.
### 9. Variable-driven cantilever example — `ex2a_canti2d_elastic_element.osmodel`
```bash
### 9. Ex 2a, parameter-driven — `ex2a_canti2d_elastic_element.osmodel`
```
File → Open → ex2a_canti2d_elastic_element.osmodel
Analyze → Cases → run "Push" or "Earthquake"
Display → Show Pushover Curve / Time-History Plot
```
This is the Ex2a cantilever tutorial recast as a project model. It is
useful when we want the same basic physics as Ex1a but with all major
dimensions and derived quantities exposed as named parameters.
Same physics as Ex 1a, but dimensions and derived quantities are
named parameters instead of literals.
### 10. Nonlinear aggregated-section cantilever — `ex2b_canti2d_inelastic_section.osmodel`
```bash
### 10. Ex 2b, aggregated section — `ex2b_canti2d_inelastic_section.osmodel`
```
File → Open → ex2b_canti2d_inelastic_section.osmodel
Analyze → Cases → run "Push" or "Earthquake"
Display → Show Pushover Curve / Time-History Plot
```
This is the first nonlinear cantilever benchmark in the tutorial series.
It demonstrates how separate axial and flexural uniaxial responses can
be aggregated into one section and used by a force-based beam-column element.
First nonlinear cantilever in the series. Separate axial and flexural
uniaxial responses aggregated into one section on a force-based
beam-column.
### 11. Fiber-section cantilever example — `ex2c_canti2d_inelastic_fiber_section.osmodel`
```bash
### 11. Ex 2c, fiber section — `ex2c_canti2d_inelastic_fiber_section.osmodel`
```
File → Open → ex2c_canti2d_inelastic_fiber_section.osmodel
Analyze → Cases → run "Push" or "Earthquake"
Display → Show Pushover Curve / Time-History Plot
```
This is the Ex2c fiber-section counterpart to Ex2b. It is useful for
checking coupled axial-flexural section behavior with inelastic concrete
and steel materials assigned directly to fibers and rebar layers.
Ex 2b's fiber counterpart. Coupled axial-flexure with concrete and
steel assigned to fibers and rebar layers directly.
### 12. Example 3 build variants — `ex3_canti2d_*.osmodel`
```bash
### 12. Ex 3 family — `ex3_canti2d_*.osmodel`
```
File → Open → ex3_canti2d_elastic_element.osmodel
Analyze → Cases → run "Push" or "Earthquake"
```
The Example 3 family is useful when we want the same cantilever analyses
to run on three different build styles: elastic element, aggregated
uniaxial section, and fiber section, all with unit-scaled parameters.
Same cantilever analyses on three build styles: elastic element,
aggregated uniaxial section, fiber section. All unit-scaled.
### 13. Modal shear-building example — `eigen_two_storey_shear_frame.osmodel`
```bash
### 13. Modal shear building — `eigen_two_storey_shear_frame.osmodel`
```
File → Open → eigen_two_storey_shear_frame.osmodel
Analyze → Cases → run "Modal-2"
Display → Animate Mode Shape
- mode 1 → in-phase storey sway
- mode 2 → out-of-phase storey sway
- mode 1 → stories sway in phase
- mode 2 → stories sway out of phase
```
This example is useful for validating modal workflows on a tiny model
that still needs multi-point constraints (`equalDOF`) to behave like an
idealized shear frame.
Validates modal workflows on a model small enough to check by hand,
with `equalDOF` doing the shear-frame duty.
### 9. Modal elastic frame example — `eigen_two_storey_one_bay_frame.osmodel`
```bash
File → Open → eigen_two_storey_one_bay_frame.osmodel
Analyze → Cases → run "Modal-2"
Display → Animate Mode Shape
- mode 1 → in-phase sway of the two storeys
- mode 2 → upper storey reverses relative to the first storey
### 14. Modal frame, Chopra 10.5 — `eigen_two_storey_one_bay_frame.osmodel`
```
This is the Chopra Example 10.5 frame counterpart to the shear-building
example above. It gives us a small modal benchmark with ordinary
beam-column frame behavior and no multi-point constraints.
File → Open → eigen_two_storey_one_bay_frame.osmodel
Analyze → Cases → run "Modal-2"
Display → Animate Mode Shape
- mode 1 → in-phase sway of both stories
- mode 2 → top story reverses against the first
```
Companion to the shear building above. Ordinary beam-column behavior,
no multi-point constraints.
### 13. Example 4 portal-frame variants
```bash
File -> Open -> ex4_portal2d_elastic_element.osmodel
Analyze -> Cases -> run "Push" or "Sine-Uniform"
Display -> Show Pushover Curve / Time-History Plot
### 15. Ex 4 portal family — `ex4_portal2d_*.osmodel`
```
The Example 4 family keeps the OpenSees split between model-building
and analysis files, but moves it into project variants. These are
useful benchmarks for pinned-base frame sway, distributed gravity on the
beam, and support-motion dynamics without depending on an external
earthquake file. The fiber-section transient is intentionally retained
as a strong nonlinear stress test and may stop early while still
producing useful partial histories.
File → Open → ex4_portal2d_elastic_element.osmodel
Analyze → Cases → run "Push" or "Sine-Uniform"
Display → Show Pushover Curve / Time-History Plot
```
Keeps the OpenSees split between model-building and analysis files,
recast as project variants. Covers pinned-base sway, distributed
girder gravity, and support-motion dynamics without an external quake
file. The fiber transient is kept as a nonlinear stress test — it may
stop early and still produce usable partial histories.
## Regenerating the .osmodel files
If you change the Python scripts, run them to regenerate the saved models:
Scripts are the source of truth, `.osmodel` files are build artifacts
checked in for convenience. Change a script, rerun it:
```bash
python examples/cantilever.py
@ -232,6 +223,5 @@ python examples/eigen_two_storey_shear_frame.py
python examples/eigen_two_storey_one_bay_frame.py
```
Each script builds the project, saves it, reloads it, and asserts a clean
round-trip. The Python source is the source of truth; the `.osmodel` files
are generated artifacts checked in for convenience.
Each script builds the project, saves it, reloads it, and asserts a
clean round-trip.