civix 0.3.0

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