Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -191,3 +191,6 @@ displacement.png
# Figures and tables written by the example scripts and template
examples/output/
templates/output/

# Claude Code agent worktrees (temporary checkouts of this repo)
.claude/worktrees/
32 changes: 32 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,38 @@ releases may still change the API).

## [Unreleased]

### Added

- New domains: `MachineElements` (bolt torque, preload and joint
stiffness, shaft diameter, spring rate and stress, bearing L10 life,
fillet welds), `Fatigue` (endurance limit, Marin factors, Goodman,
Soderberg, Gerber and ASME-elliptic safety factors, S-N curve) and
`Psychrometrics` (saturation pressure, humidity ratio, relative humidity,
dew point, enthalpy, specific volume, wet bulb). `Material` gains
Johnson buckling, slenderness ratios and an Euler/Johnson chooser.
Tests check published ASHRAE and Shigley table values.
- `fpc-mcp --domains fluids,thermo`: also serve each calculation in those
domains as its own MCP tool, with the registry's input schema, for
capable models that do better calling a tool directly.
- `fpc.uncertainty`: Monte Carlo on any calculation. Give inputs as
`Normal`, `Uniform` or `Triangular` distributions; get the mean,
standard deviation, percentiles, a 95 % interval and each input's share
of the spread. Also `fpc uncertainty` (`velocity=normal:2,0.1`).
- `fpc.report` and `fpc report`: a Markdown calc sheet for any calculation
(method, inputs with units, defaults, result, optional uncertainty,
review checklist), ready for a design file or `pandoc`.
- `apps/calculator.py`: a Streamlit web form for every calculation,
generated from the registry, with uncertainty and calc-sheet tabs.
- `scripts/try_local_model.py`: ask an Ollama model engineering questions
through `fpc-mcp` and check its answers against the library.

### Changed

- The MCP `calculate` tool's `arguments` is optional so that a model
which puts the inputs beside `key` gets a precise correction instead of
a validation error it cannot act on.
- mypy now requires every function in `fpc/` to be fully annotated.

## [0.1.0] - first PyPI release

### Added
Expand Down
5 changes: 4 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,10 @@ The original design lives in [SPEC.md](SPEC.md); the improvement backlog lives i
## Current state

- `main.py` — displacement demo (closed form, `scipy` integration, library call) that prints results and saves a plot.
- `fpc/` — the installable package (import name `fpc`, distribution name `first-principles-code`). One class per engineering domain (Dynamics, Statics, Modal, Thermo, Fluids, Material, Gear, Electrical, Mechatronics, Controls, Utility, Design, Properties, plus the radiology set Radiation, Radiography, CT, MRI, Ultrasound, Dicom), the shared Pint registry in `fpc/units.py`, and the unit-aware `Beam` dataclass.
- `fpc/` — the installable package (import name `fpc`, distribution name `first-principles-code`). One class per engineering domain (Dynamics, Statics, Modal, Thermo, Fluids, Psychrometrics, Material, Gear, MachineElements, Fatigue, Electrical, Mechatronics, Controls, Utility, Design, Properties, plus the radiology set Radiation, Radiography, CT, MRI, Ultrasound, Dicom), the shared Pint registry in `fpc/units.py`, and the unit-aware `Beam` dataclass.
- `fpc/registry.py` — introspects every domain method (type hints + `[unit]` docstring tags) into a catalogue with JSON Schemas; drives `fpc search/describe/run`, the MCP server (`fpc/mcp_server.py`, command `fpc-mcp`, optional `mcp` extra) and the generated `llms.txt`. See `docs/ai.md`.
- `fpc/uncertainty.py` (Monte Carlo on any calculation, `fpc uncertainty`) and `fpc/report.py` (Markdown calc sheets, `fpc report`) — both built on the registry. See `docs/trusting-results.md`.
- `apps/calculator.py` — Streamlit form for every calculation, generated from the registry (`uv run streamlit run apps/calculator.py`).
- `gui.py` — tkinter MATLAB-style console; the `Session` class is GUI-free and tested.
- `tests/` — pytest suite, run in CI (`.github/workflows/tests.yml`).
- `examples/` — one self-contained worked problem per script; `templates/` — copy-and-adapt starting scripts; `notebooks/` — Jupyter notebooks; `fpc/data/` — cited reference tables (CSV); `docs/` — mkdocs site sources and guides.
Expand All @@ -37,6 +39,7 @@ uv run pre-commit install # enable git hooks (ruff + pytest)
uv run fpc llms-txt > llms.txt # regenerate after changing public methods (a test checks it)
uv build # build sdist + wheel; releasing steps are in docs/releasing.md
uv run scripts/python_support.py check # supported Python versions consistent everywhere
uv run --extra mcp scripts/try_local_model.py --model qwen3:14b --think off # MCP server vs a local Ollama model
uv run -p 3.11 pytest # run the tests on a specific Python (CI runs every supported one)
```

Expand Down
60 changes: 56 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,9 @@ You get:
integration of constant acceleration, and numerical integration of a
time-varying acceleration).
- **`fpc/`** — an installable package with one well-documented class per
engineering domain (dynamics, statics, thermo, fluids, materials, gears,
electrical, mechatronics, modal/vibration, controls), a set of radiology /
engineering domain (dynamics, statics, thermo, fluids, psychrometrics,
materials, gears, machine elements, fatigue, electrical, mechatronics,
modal/vibration, controls), a set of radiology /
medical-imaging classes, `Design` (root finding and optimization),
`Properties` (cited reference tables with interpolation), and a `Utility`
class for files, tables, and dialogs.
Expand Down Expand Up @@ -334,6 +335,43 @@ Units: methods that take plain numbers expect **SI units** (the docstring
says so for every parameter); use Pint at the boundaries where units are
mixed. See [docs/units.md](https://github.com/kovirlabs/first-principles-code/blob/main/docs/units.md).

## Machine design, fatigue & HVAC

The everyday sizing checks of a mechanical or HVAC engineer, following
Shigley's *Mechanical Engineering Design* and the *ASHRAE Handbook -
Fundamentals*: bolts, shafts, springs, bearings and welds
(`MachineElements`), stress-life fatigue (`Fatigue`), Euler/Johnson column
buckling (`Material`), and moist-air properties (`Psychrometrics`).

```python
from fpc import Fatigue, MachineElements, Material, Psychrometrics

me = MachineElements()
me.bolt_tightening_torque(preload=37.9e3, nominal_diameter=0.012) # 91 N*m (K = 0.2)
me.bearing_l10_life_hours(dynamic_load_rating=30e3, equivalent_load=3e3, speed_rpm=1500) # 11 111 h

# Fatigue: endurance limit -> Marin factors -> mean-stress criterion.
f = Fatigue()
se = f.marin_endurance_limit(
specimen_endurance_limit=f.endurance_limit_steel(ultimate_strength=690e6),
surface_factor=f.surface_factor(ultimate_strength=690e6, finish="machined"),
size_factor=f.size_factor(diameter=0.03),
) # 237 MPa
f.goodman_safety_factor(
alternating_stress=120e6, mean_stress=80e6, endurance_limit=se, ultimate_strength=690e6
) # 1.61

# Column buckling: picks Euler or Johnson from the slenderness ratio.
Material().critical_buckling_load(
modulus=200e9, moment_of_inertia=1.917e-8, area=4.909e-4, length=0.5, yield_strength=250e6
) # {'critical_load': 97848.2, 'formula': 'johnson', 'slenderness_ratio': 80.0, ...}

# Psychrometrics (temperatures in degC, RH as a fraction): solved with brentq.
psy = Psychrometrics()
psy.dew_point(temperature_c=25, relative_humidity=0.5) # 13.9 degC
psy.wet_bulb(temperature_c=25, relative_humidity=0.5) # 17.9 degC
```

## Radiology & medical imaging

Six classes cover the physics and image handling a radiology student
Expand Down Expand Up @@ -482,8 +520,18 @@ without writing any code:
fpc search "pipe pressure drop" # find a calculation
fpc describe Fluids.pipe_flow # its inputs, units and formula
fpc run Fluids.reynolds_number density=998 velocity=2 length=0.05 viscosity=0.001

# How sure is the answer? Give inputs a spread and run 10 000 cases (Monte Carlo)
fpc uncertainty Fluids.reynolds_number density=998 velocity=normal:2,0.1 length=0.05 viscosity=0.001

# File it: a Markdown calc sheet with method, inputs and units, result, review checklist
fpc report Fluids.reynolds_number density=998 velocity=2 length=0.05 viscosity=0.001 --out re.md
```

Or use every calculation from a web form, with uncertainty and calc-sheet
tabs: `uv run streamlit run apps/calculator.py`. See
[docs/trusting-results.md](https://github.com/kovirlabs/first-principles-code/blob/main/docs/trusting-results.md).

## Use it with AI assistants (Ollama, LM Studio, Claude, ...)

Small local models are unreliable at arithmetic. The `fpc-mcp` command is an
Expand Down Expand Up @@ -540,17 +588,21 @@ first-principles-code/
│ ├── cli.py # the `fpc` terminal command
│ ├── registry.py # catalogue of every calculation (types, units, schemas)
│ ├── mcp_server.py # `fpc-mcp`: MCP server for AI apps
│ ├── uncertainty.py # Monte Carlo on any calculation
│ ├── report.py # Markdown calc sheets
│ ├── hints.py # shared type-hint names (ArrayLike, FloatArray)
│ ├── data/ # cited reference tables (CSV) + sources
│ ├── dynamics.py, statics.py, modal.py, thermo.py, fluids.py,
│ ├── material.py, gear.py, electrical.py, mechatronics.py, controls.py
│ ├── material.py, gear.py, electrical.py, mechatronics.py, controls.py,
│ ├── machine_elements.py, fatigue.py, psychrometrics.py
│ └── radiation.py, radiography.py, ct.py, mri.py, ultrasound.py, dicom.py
├── examples/ # worked problems, one script each (+ tools/ ladder)
├── apps/ # Streamlit calculator: a form for every calculation
├── templates/ # copy-and-adapt starting script
├── notebooks/ # Jupyter notebooks
├── docs/ # guides + API docs site sources (mkdocs.yml)
├── tests/ # pytest suite (uv run pytest)
├── scripts/ # maintenance scripts (python_support.py: Python version ratchet)
├── scripts/ # maintenance: python_support.py (version ratchet), try_local_model.py (MCP + Ollama)
├── pyproject.toml # metadata, dependencies, tool config
├── PACKAGES.md # Python packages by engineering field
├── SPEC.md # original project design spec
Expand Down
66 changes: 41 additions & 25 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ whole: structure, tooling, docs, and discoverability.
number next to it. Items marked **(decision needed)** wait on the maintainer's
call before work starts. Keep items in priority order within each section.

_Last reviewed: 2026-11-07. Sections 0-8 were built in #6 (branch
`feat/roadmap-buildout`); see "Follow-ups" for what remains._
_Last reviewed: 2026-11-07. Sections 0-8 were built in #6, most of 9-10 in #8,
and the rest of 9-11 on branch `feat/roadmap-next`; see "Follow-ups" for what
remains._

---

Expand Down Expand Up @@ -144,13 +145,13 @@ composing the code directly, so for them we document the API compactly.
`list_domains`, `search_calculations`, `describe_calculation`,
`calculate`, `list_reference_tables`. Never expose arbitrary code
execution. Ships as the `mcp` extra: `pip install "first-principles-code[mcp]"`.
- [ ] **MCP: optional direct tools.** A `--domains fluids,thermo` flag that
also exposes those methods as individual tools with their own schemas
(better for capable models; the SDK builds schemas from signatures, so
this needs a registry-schema -> tool adapter).
- [ ] **Try the MCP server with real local models** (LM Studio + a Qwen /
Llama / Mistral tool-calling model, Open WebUI + Ollama) and tune the tool
descriptions and `INSTRUCTIONS` from what goes wrong.
- [x] **MCP: optional direct tools.** `fpc-mcp --domains fluids,thermo`
also serves each of those calculations as its own tool, with the
registry's schema.
- [x] **Try the MCP server with real local models.** Done with Ollama
(qwen3:14b, qwen2.5:7b, qwen2.5-coder:14b) through
`scripts/try_local_model.py`; results, and the fixes they led to, are in
`docs/ai.md`. The LM Studio and Open WebUI apps themselves: see Follow-ups.
- [x] **`fpc search` / `fpc describe` / `fpc run` CLI subcommands**, driven
by the registry, so every method is reachable from the terminal.
- [x] **`llms.txt` + `AGENTS.md`** for coding agents: a generated, compact
Expand Down Expand Up @@ -182,22 +183,23 @@ composing the code directly, so for them we document the API compactly.
across all of them and a ratchet: `scripts/python_support.py`
(`check` / `status` / `set`) plus a monthly workflow that opens an issue
when a version is released or retired. See `docs/python-versions.md`.
- [ ] **Streamlit app generated from the registry**: one form per method,
for free, using the existing `apps` dependency group.
- [x] **Streamlit app generated from the registry**: `apps/calculator.py`,
one form per method, with uncertainty and calc-sheet tabs.

## 11. Trust and day-to-day usefulness

- [ ] **Calc reports.** Export a calculation to Markdown/PDF with the
equation, inputs with units, result, and source citation, the way a
checked hand calc is filed for review (compare `handcalcs`).
- [ ] **Worked-example tests with citations.** Tests that reproduce
published textbook examples (e.g. "Shigley Ex. 4-7") so users can trust
the numbers. Pairs with the data-verification follow-ups below.
- [ ] **Domain gaps engineers hit daily:** machine elements (bolts, shafts,
springs, bearings, welds), fatigue (Goodman/Soderberg), column buckling,
psychrometrics/HVAC.
- [ ] **Uncertainty on any calculation:** a Monte Carlo helper that wraps a
registry method and samples its inputs.
- [x] **Calc reports.** `fpc.report` / `fpc report`: Markdown calc sheet
with the method, inputs with units, result, library version and a review
checklist (PDF/Word via pandoc).
- [x] **Worked-example tests with citations** for the new machine-element,
fatigue, buckling and psychrometrics methods (ASHRAE Fundamentals tables,
Shigley Table 6-5). Older domains: see Follow-ups.
- [x] **Domain gaps engineers hit daily:** `MachineElements` (bolts, shafts,
springs, bearings, welds), `Fatigue` (Marin factors, Goodman, Soderberg,
Gerber, ASME-elliptic, S-N), Johnson/Euler column buckling on `Material`,
and `Psychrometrics`.
- [x] **Uncertainty on any calculation:** `fpc.uncertainty.monte_carlo`
and `fpc uncertainty`, with intervals and input sensitivity.

---

Expand All @@ -211,13 +213,27 @@ Items found while building sections 0-8.
values are typical published figures but were entered from reference
knowledge, not copied from a fetched source.
- [ ] **Verify `fpc/data/w_shapes.csv` against the AISC Shapes Database v16
spreadsheet.** A test confirms every row is physically self-consistent
spreadsheet.** aisc.org refuses automated downloads, so this needs the
spreadsheet downloaded by hand. A test confirms every row is physically self-consistent
(Sx = Ix/(d/2), weight = 3.4 x A), which catches typos but not a
consistently wrong row. Extend the table while doing this.
- [ ] **Plan the move off Material for MkDocs**, which reaches end of life on
2027-05-05. Its successor, Zensical, reads the existing `mkdocs.yml`.
- [ ] **Tighten mypy** module by module as type hints are added
(`disallow_untyped_defs` per module).
- [x] **Tighten mypy:** `disallow_untyped_defs` and
`disallow_incomplete_defs` for all of `fpc/`.
- [ ] **Spot-check the equation and table numbers** cited in
`fpc/machine_elements.py`, `fpc/fatigue.py` and `fpc/psychrometrics.py`
against Shigley 10th ed. and ASHRAE Fundamentals 2017. The values were
checked; some equation numbers were written from memory.
- [ ] **Psychrometrics enhancement factor.** Humidity ratios use the
ideal-gas equations and differ from ASHRAE Table 2 by about 0.4 %.
- [ ] **Cited worked-example tests for the older domains** (Fluids, Thermo,
Statics, ...), e.g. Moody-chart friction factors, textbook conduction.
- [ ] **Try `fpc-mcp` in the LM Studio and Open WebUI apps**, and add more
question types to `scripts/try_local_model.py` (Properties lookups,
multi-step problems).
- [ ] **An MCP tool for uncertainty** (`calculate_with_uncertainty`) if
model users ask for it; left out for now to keep the tool list at five.
- [ ] Consider an InSpice row in place of PySpice in `PACKAGES.md` once
InSpice has a longer release history.

Expand Down
Loading
Loading