civix

A structural-engineering design library for Python where Jupyter notebooks are the primary deliverable — living calculation documents suitable for review and submission.

Status: foundation cycle. The cross-cutting infrastructure (errors, logging, notebook display, and the Quarto export pipeline) is in place; structural-domain modules (codes, elements, materials) arrive in later cycles.

Civix has two rendering paths:

• civix.display — the live view inside a running notebook (self-rendering PASS/FAIL cards, headers, input tables).
• civix.report — the printed deliverable: scaffold a Quarto project and render a notebook to PDF/HTML/docx.

Plus domain tooling:

• civix.csi + hosts/csi/ — ETABS → SAFE raft pipeline: read per-building ETABS exports (Excel or live OAPI), place them into one SAFE frame with full 6-DOF reaction handling, emit a validated raft JSON + Plotly overlay, and build/run the SAFE mat model. See docs/csi/etabs2safe-guide.md.
• civix.csilib + hosts/csilib/ — object-level CSI OAPI wrapper for ETABS, SAP2000 and SAFE: typed enums, frozen dataclasses, pandas DataFrames, context-managed launch/attach with a hardened connection recipe, and SAFE's database-table layer as DataFrame in/out. Configured by the repo-root csilib.toml. See src/civix/csilib/README.md and docs/csilib/csilib-guide.md.
• civix.site + hosts/grasshopper/ — Rhino/Grasshopper site tools: point-cloud ground-Z extraction (LAS/LAZ) and Revit toposolid break-line creasing. Pure engines are unit-tested here; thin GH components run on the host. See docs/gh-tools-cookbook.md.
• app/csi_safe_builder/ — a Streamlit control panel over the civix.csi single-model pipeline (read ETABS → assemble the raft → build the SAFE .fdb), run on the Windows/SAFE host. Not shipped in the wheel. See app/csi_safe_builder/README.md.

Quickstart

uv sync                  # core library only
uv sync --extra notebook # add Jupyter + handcalcs (optional, needed to run notebooks)
uv run poe demo          # executes the foundation reporting demo notebook

In a notebook:

from civix.display import setup_notebook, CheckResult, CalculationReport

setup_notebook(project_name="Office Building A", engineer="J. Doe")

report = CalculationReport(title="Beam B-101")
report.add(CheckResult("Bending", unity_ratio=0.73, demand=180.0,
                       capacity=245.6, demand_unit="kNm", capacity_unit="kNm"))
report  # renders a styled PASS/FAIL report

Exporting a PDF

Scaffold a Quarto project, then render a notebook. Export needs the external Quarto CLI plus a LaTeX engine (e.g. TinyTeX).

from civix.report import init_calc_project, render_report

init_calc_project("calcs", include_sample=True)   # writes Quarto templates
render_report("calcs/sample-calcsheet.ipynb")      # -> calcs/sample-calcsheet.pdf

The scaffold also has a CLI:

uv run python -m civix.report calcs --sample

Command-line tools

Installing civix also installs three console commands:

civix-health              # read-only doctor: version, optional extras, Quarto CLI,
                          # csilib.toml discovery (never launches ETABS/SAP2000/SAFE)
civix-init-config [DIR]   # scaffold a starter csilib.toml (commented defaults) into DIR
civix-init-calc DIR       # scaffold the Quarto calc templates (same as python -m civix.report)

All three work on a bare pip install civix — optional extras are only detected, never imported.

For a complete worked example — an ACI 318M-25 (SI) flexure calc note that pairs handcalcs equation rendering with civix CheckResult/CalculationReport cards — see notebooks/examples/sample-calcsheet.ipynb and render it with uv run --extra notebook quarto render notebooks/examples/sample-calcsheet.ipynb --to pdf.

Conventions

Notebooks are submission-grade calculation documents. Units are never encoded in identifier names — use clean engineering symbols (A_s, M_u, f_c) and annotate the unit on the value (a handcalcs trailing comment, the value string in calc_input_table, demand_unit/capacity_unit on CheckResult, or a library docstring). The default system is metric: N/mm/MPa for section and material values, kN/m/kPa/kN·m for loads and spans. Convert at boundaries; never mix unit systems silently. Full discipline lives in docs/calc-note-style-guide.md and CLAUDE.md.

Development

Dev tasks run through Poe the Poet ([tool.poe.tasks] in pyproject.toml) so they work identically on Windows, macOS and Linux:

uv run poe check       # format, lint, type-check, test (654 tests; 27 live-vendor tests skip unless --run-* flags are passed)
uv run poe gh39-check  # syntax-guard the civix.site engines + GH host scripts on CPython 3.9

Run the csilib live-vendor integration suite (on the Windows/CSI host):

uv run pytest tests/integration/csilib --run-etabs --run-sap2000 --run-safe

Run the Streamlit app (on the Windows/SAFE host):

uv run --extra csi --extra streamlit streamlit run app/csi_safe_builder/main.py

Repository layout

src/civix/                 # the installable package (ships in the wheel)
├─ exceptions.py           #   CivixError hierarchy
├─ log_config.py           #   loguru setup
├─ display/                #   live in-notebook PASS/FAIL rendering
├─ report/                 #   Quarto PDF/HTML/docx export (+ templates/ package data)
├─ utils/                  #   formatting + validation helpers
├─ csi/                    #   ETABS → SAFE raft pipeline (optional `csi` extra)
├─ csilib/                 #   CSI OAPI wrapper — ETABS/SAP2000/SAFE (optional `csilib` extra)
├─ site/                   #   Grasshopper engines (optional `site` extra)
│  ├─ pointcloud/          #     LAS/LAZ ground-Z KD-tree engine + origin-shift
│  └─ topo/                #     Revit toposolid break-line helpers
└─ core/ elements/ codes/ loads/   # structural-domain stubs (later cycles)

hosts/                     # host-only adapter scripts — NOT in the wheel, ruff/ty-excluded
├─ csi/                    #   ETABS/SAFE OAPI entry scripts, gates, LISP, A.1–A.15 spike record
├─ csilib/                 #   csilib diagnostics, vendor gates, notebook generators, API index
└─ grasshopper/            #   Rhino/Revit GH components (load engines by file path)
   └─ topo_breaklines/

app/                       # host-level Streamlit UIs — NOT in the wheel, ty-excluded
└─ csi_safe_builder/       #   settings.py / actions.py / main.py over the civix.csi pipeline

tests/
├─ unit/                   # mirrors library modules (test_csi/, test_site/, …)
├─ integration/            # external toolchains — Quarto, plus csi/
└─ notebooks/              # deliverable calc-note benchmark suites

docs/
├─ csi/                    # civix.csi invariants guide + OAPI references
├─ csilib/                 # civix.csilib binding domain reference (csilib-guide.md)
├─ gh-tools-cookbook.md    # the two-layer Grasshopper tool pattern
├─ standards/              # binding engineering / API / debugging protocols
└─ superpowers/            # implementation plans + design specs

Three deliberately separate layers: engines (src/civix/…, pure, tested, in the wheel), hosts (hosts/…, thin vendor-API adapters that run only inside ETABS/SAFE or Rhino/Revit), and apps (app/…, host-level Streamlit UIs over the engines). Only src/civix/… ships in the wheel; hosts and apps live outside it and — like the host scripts — call the engines rather than reimplement them.