lcf-strain-life

Readme | Physics Review | Agent Usage | Changelog | MIT License

An AI-agent-native toolkit for fatigue analysis of materials. It is a Python library plus an MCP server, so AI agents can run the whole analysis by calling tools.

Provide your own strain-controlled fatigue test data and get the standardized reduction, fitted material constants, life predictions, and plots. Results are reproducible and are saved for recall.

Why this exists: plenty of fatigue software exists, but none is built for AI agents to drive directly. The agent-native design over MCP is the point. Every capability is reachable through tools an agent can call.

Convention: all analysis uses true stress and true strain. Engineering input is converted at ingestion. The fatigue exponents b and c are negative throughout.

What it does

The toolkit is general purpose and material agnostic. It centers on strain-life reduction of raw strain-controlled test data and per-cycle evolution, end to end from lab exports. Other open libraries cover parts of this ground. pyLife and reliability implement strain-life equations, and py-fatigue and fatpack cover cycle counting and stress-life. None of them focus on reducing raw LCF test data or on driving the analysis from an AI agent. It is input compatible with the pandas data shapes of pyLife and py-fatigue.

Install

python -m venv .venv
.venv\Scripts\activate            # Windows
pip install -e ".[mcp,dev]"

Requires Python 3.11 or newer.

Quick start, library

import lcf

# fit strain-life constants from per-test reduced data, here SAE 1137
fit = lcf.fit_strain_life(
    total_strain_amp=[0.009, 0.007, 0.005, 0.003, 0.002, 0.00175],
    stress_amp=[553, 522, 464, 405, 350, 319],         # MPa, half-life
    reversals=[4234, 7398, 14768, 77104, 437498, 3327958],
    E=208000,                                           # MPa
    min_plastic_strain=5e-4,   # exclude near-runout points from the plastic branch
)
print(fit.coffin_manson.eps_f, fit.coffin_manson.c)   # about 1.11, -0.62
print(fit.basquin.sigma_f, fit.basquin.b)             # about 1073 MPa, -0.084
print(fit.transition_reversals)                        # about 22,000 reversals

Quick start, MCP server

The MCP server is the point of this project: it is how an AI agent drives the whole analysis by calling tools.

lcf-mcp                # runs the stdio MCP server
# or
python -m lcf

Register with Claude Code or Claude Desktop over stdio:

{ "mcpServers": {
    "lcf": { "command": "lcf-mcp" } } }

Quick start, graphical interface (no code)

A secondary, optional interface for people who do not program and are not using an AI agent. The agent-native MCP server above is the primary way to use this toolkit. The graphical app is a thin convenience layer over the same library functions, adding no capability the tools do not already expose.

It is a guided local app in the browser: upload test files or type in reduced data, fit the constants, predict life, export plots and a report. Everything runs on your machine and no data leaves it.

pip install "lcf-strain-life[gui]"
lcf-gui

The gui extra ships with the next PyPI release. Until then, install from a clone of this repository with pip install -e ".[gui]".

The app walks through the workflow in order: analyze raw test files, fit strain-life constants, predict life, estimate constants when no fatigue data exists, and export. A bundled published example dataset (SAE 1137) lets you try the whole flow without any files.

A standalone Windows exe (no Python needed) is attached to GitHub releases starting with the next release. Download it, double-click, and the app opens in the browser. Two honest caveats: the exe unpacks itself on every launch, so starting takes a while, and it is currently unsigned, so Windows SmartScreen will warn on first run. Choose "More info", then "Run anyway".

Documentation

• The documentation site renders installation, usage, a tutorial reproducing a published SAE 1137 analysis, the statistics guide, and the API reference.
• docs/PHYSICS_REVIEW.md is the science-only physics record: every equation defined and cited, no software detail. docs/PHYSICS_REVIEW.pdf is the same content typeset with a reviewer sign-off table, the file to share with a materials scientist for review.
• examples/ holds runnable scripts: a strain-life fit and a machine-style CSV ingestion.
• docs/AGENT_USAGE.md describes the MCP tools and the compute, save, recall pattern for AI agents using the toolkit.
• CHANGELOG.md is the chronological log of changes.

Open data

The toolkit defines versioned, machine-readable interchange formats for strain-life data, specified in docs/INTERCHANGE.md with JSON Schemas in docs/schemas/. A citable seed collection ships at docs/data/seed_collection.json, six published SAE 1137 tests and three verified constant sets, every value re-tabulated from its cited source. It is a schema-reference seed, not yet a database at scale. Contributions of strain-controlled data, especially with per-cycle evolution, are welcome under the rules in docs/CONTRIBUTING-DATA.md, and lcf-validate checks any document from the command line.

Project layout

src/lcf/            core library and MCP server
tests/              unit tests including golden-value validation, SAE 1137
examples/           runnable example scripts
docs/               documentation site sources, physics PDF, interchange
                    spec, JSON Schemas, and the seed data collection
website/            the landing page, plain HTML and CSS

Authors and citation

David Fieser and Hugh Shortt. Both authors contributed equally to this project. To cite the software, use the "Cite this repository" button on GitHub or CITATION.cff.

License

MIT. See LICENSE.