civix 0.3.1

Structural-engineering calculation library where Jupyter notebooks are the living, reviewable deliverable.

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.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.

Quickstart

uv sync                  # core library only
uv sync --extra notebook # add Jupyter + handcalcs (optional, needed to run notebooks)
make 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

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

make check       # format, lint, type-check, test (340 tests)
make gh39-check  # syntax-guard the civix.site engines + GH host scripts on CPython 3.9

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)
├─ 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
└─ grasshopper/            #   Rhino/Revit GH components (load engines by file path)
   └─ topo_breaklines/

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
├─ gh-tools-cookbook.md    # the two-layer Grasshopper tool pattern
├─ standards/              # binding engineering / API / debugging protocols
└─ superpowers/            # implementation plans + design specs

Two deliberately separate layers throughout: engines (src/civix/…, pure, tested, in the wheel) and hosts (hosts/…, thin vendor-API adapters that run only inside ETABS/SAFE or Rhino/Revit, excluded from the wheel and static checks).