TensorDerive — Automated Mechanics Derivation for Tensor Analysis

Coupling LLM reasoning with Computer Algebra Systems (CAS) for mechanics theory derivation.
Core approach: LLM handles strategy (choosing correct tensor identities, constructing constitutive
hypotheses, designing variational frameworks), while CAS handles symbolic execution (tensor algebra,
differentiation/integration, index simplification, automatic differentiation). The two interact
through the MCP protocol.

Design Philosophy

flowchart TD
    A["User Input<br/>(natural language / LaTeX)"]
    B1["<b>Strategy</b> (LLM Agent)<br/>- Identities<br/>- Decompose<br/>- Hypotheses"]
    B2["<b>Symbolic (CAS)</b><br/>- sympy-mcp<br/>- tensorgrad<br/>- FElupe AD<br/>- Mathematica"]
    C["<b>Verification Layer</b><br/>- Cross-validation (CAS alt path)<br/>- Numerical check (FElupe/numpy)<br/>- Dimensional analysis"]
    D["<b>Compilation Layer</b><br/>- LaTeX derivation document<br/>- Reproducible CAS code archive<br/>- Feeds into academic-paper skill"]
    A --> B1
    B1 --> B2
    B1 --> C
    B2 --> C
    C --> D

Quick Start

Minimal command:

Derive the tangent stiffness tensor for NeoHookean hyperelastic material,
assuming near-incompressibility.

Tensor derivation:

Derive the components of the Riemann curvature tensor in spherical coordinates.
Write out the Ricci tensor and scalar curvature.

Constitutive derivation:

Derive the Cauchy stress tensor for the Arruda-Boyce 8-chain model,
and give the closed-form expression for the material tangent moduli.

Variational derivation:

Derive the weak form of the nonlinear elasticity problem in Total Lagrangian
description, and give the Newton-Raphson tangent stiffness matrix expression.

Execution flow:

1. Formalize — Convert natural language problem into symbolic math form (variables, tensor orders, assumptions)
2. Strategize — Plan derivation path, select CAS tools and operation sequences
3. Execute — Perform tensor algebra, differentiation, simplification via CAS
4. Verify — Cross-validation + numerical instantiation verification
5. Compile — Generate LaTeX derivation document + reproducible CAS code

Trigger Conditions

Trigger Keywords

English: derive, tensor calculus, constitutive derivation, variational derivation,
weak form, Eshelby, elasticity, plasticity, hyperelastic, continuum mechanics,
computational mechanics, Christoffel, Riemann, index notation

Chinese: 推导, 张量应推导, 本构推导, 变分推导, 弱形式, Eshelby, 弹性, 塑性,
超弹性, 连续介质力学, 计算力学, Christoffel, Riemann, 指标表示

Mode Selection

Scenario	Mode	Description
Clear derivation target	full	Complete derivation workflow
Need guidance on path	guided	Socratic-style derivation guidance
Check existing derivation	verify	Validate and correct existing expressions
Fast symbolic computation	quick	CAS execution only, no strategic planning
Explore constitutive space	explore	Derivation under multiple constitutive hypotheses
Journal-quality derivation	journal	Complete proof chain + literature comparison + numerical validation

Agent Team (6 Agents)

#	Agent	Role	Phase
1	derivation-architect	Strategy planning: decomposes natural language into symbolic operation sequences, chooses tensor identities, designs decomposition strategies	Phase 0
2	tensor-specialist	Tensor algebra execution: index operations via sympy-mcp, covariant/contravariant ops, tensor contractions, Riemannian geometry	Phase 1
3	mechanics-specialist	Solid mechanics derivation: constitutive model derivation, AD for stress-strain, weak-form calculus, FElupe/FEniCS integration	Phase 1
4	verification	Verification: alternative-path cross-validation, numerical instantiation, dimensional analysis, consistency checks	Phase 2
5	derivation-compiler	Compilation: LaTeX derivation doc, CAS operation log, reproducible code package	Phase 3
6	cas-orchestrator	CAS orchestration: manages sympy-mcp / Wolfram-MCP / FElupe calls, caches intermediate results	All phases

Orchestration Flow (4 Phases)

flowchart TD
    U["<b>User Input</b><br/>Derive [quantity] under [conditions/assumptions]<br/>for [target expression]"]

    subgraph P0["<b>Phase 0: Formalize &amp; Strategize</b> (FORMALIZE)"]
        direction TB
        P0A["<b>derivation-architect</b><br/>Parse problem: variables, tensor orders,<br/>assumptions, coordinate system<br/>Strategy: index vs. tensor method,<br/>direct vs. automatic differentiation<br/>Select CAS tools<br/><i>Output: Formalized Problem +<br/>Derivation Blueprint</i>"]
        P0B["<b>cas-orchestrator</b><br/>Establish CAS sessions<br/>(sympy-mcp / Wolfram-MCP / FElupe)<br/>Register symbolic variables and tensors"]
        P0C["<b>** User confirms derivation plan **</b>"]
        P0A --> P0B --> P0C
    end

    subgraph P1["<b>Phase 1: Symbolic Derivation</b> (DERIVE)"]
        direction TB
        P1A["<b>tensor-specialist</b><br/><i>Via sympy-mcp:</i> metric, Christoffel symbols,<br/>Riemann/Ricci/Einstein tensors,<br/>covariant differentiation<br/><i>Via tensorgrad:</i> diagram simplification,<br/>chain rule expansion, code generation"]
        P1B["<b>mechanics-specialist</b><br/><i>Via FElupe + hyperelastic:</i> strain energy<br/>function, 2nd PK stress, Cauchy stress,<br/>tangent moduli<br/><i>Via sympy-mcp:</i> deformation gradient,<br/>strain conversions, rate-form derivation<br/><i>Via matadi:</i> user materials, UMAT output"]
    end

    subgraph P2["<b>Phase 2: Verification</b> (VERIFY)"]
        P2A["<b>verification</b><br/>Alternative-path cross-validation<br/>(e.g., sympy vs. tensorgrad)<br/>Numerical instantiation (FElupe)<br/>Dimensional analysis<br/>Symmetry checks (stress, tangent moduli)<br/>Consistency with classical results<br/><i>Output: Verification Report<br/>(PASS / WARN / FAIL)</i>"]
    end

    subgraph P3["<b>Phase 3: Compile Output</b> (COMPILE)"]
        P3A["<b>derivation-compiler</b><br/>LaTeX derivation document<br/>(assumptions, CAS I/O, expressions,<br/>verification results)<br/>Reproducible CAS code package<br/>Derivation Passport<br/>Optional: feed into academic-paper"]
    end

    U --> P0
    P0 --> P1
    P1 --> P2
    P2 --> P3

Checkpoint Rules

1. ⚠️ IRON RULE: Phase 0 derivation plan MUST be confirmed by user before execution
2. Phase 1 verification: After every tensor operation, output intermediate results in LaTeX
3. Phase 2 verification: Every critical derivation step MUST have at least one verification basis
4. Numerical check rule: Core results MUST be numerically instantiated with at least 3 parameter sets
5. Symmetry check: Derivation results under symmetry assumptions MUST satisfy corresponding symmetries
6. Identity check: Use known identities (e.g., Bianchi identities) to verify self-consistency

MCP Tool Integration

The system connects to the following CAS tools via the MCP protocol at runtime:

MCP Server	Tool Scope	Setup
sympy-mcp	Symbolic algebra, equation solving, differentiation/integration, matrices, ODEs/PDEs, tensor calculus (Ricci/Einstein/Weyl), vector calculus	git clone https://github.com/sdiehl/sympy-mcp.git
Wolfram-MCP	Arbitrary Wolfram Language computation, analytic/numeric integration, symbolic simplification, matrix operations	git clone https://github.com/paraporoco/Wolfram-MCP.git
Built-in FElupe	Continuum mechanics FEM, constitutive model AD	pip install felupe[all]
Built-in tensorgrad	Symbolic tensor networks, auto chain rule, PyTorch code generation	pip install tensorgrad

Symbolic Execution Protocol

Each CAS call follows a standardized protocol:

## CAS Operation Record
operation_id:  "christoffel_from_metric"
cas_backend:   "sympy-mcp"
tool:          "calculate_tensor"
input_metric:  "g_{mu nu} = diag(-1, 1, r^2, r^2 sin^2(theta))"
parameters:    { "tensor": "Christoffel", "coordinates": "spherical" }
output:        "Gamma^r_{theta theta} = -r"
              "Gamma^{theta}_{r theta} = 1/r"
              "Gamma^{phi}_{r phi} = 1/r"
              "Gamma^{phi}_{theta phi} = cot(theta)"
latex:         "\Gamma^{r}_{\theta\theta} = -r, \quad ..."
verification:  { method: "bypass_manual_check", status: "PASS" }

Journal-Quality Standards

This system targets derivation quality comparable to top mechanics journals:

• Journal of the Mechanics and Physics of Solids (JMPS)
• Computer Methods in Applied Mechanics and Engineering (CMAME)
• International Journal of Solids and Structures (IJSS)
• International Journal of Plasticity (IJP)
• Journal of Applied Mechanics (JAM)

Output derivation documents must satisfy:

1. All tensor fields explicitly define their order, symmetry, and domain
2. Constitutive model derivations clearly state thermodynamic constraints (irreversibility, convexity, material objectivity)
3. All derivation steps are reproducible line-by-line (CAS output as evidence chain)
4. Limiting cases degenerate to classical results (e.g., finite deformation → small strain)

Known Limitations

• Non-deterministic decisions: Constitutive model selection, identity selection, etc. require LLM judgment and carry uncertainty
• CAS coverage: sympy.tensor is primarily for differential geometry; general nonlinear tensor operations require FElupe/tensorgrad complement
• Computational performance: Symbolic computation of high-order tensors (e.g., 4th-order tangent moduli in full component form) may consume significant memory
• No theorem proving: The current system does not output Lean/Coq-verifiable proof objects, but retains CAS execution as evidence

Operating Modes

Mode	Trigger	Output	Use Case
full	"derive"	Full derivation document + reproducible CAS package	Clear derivation target
guided	"guide my derivation"	Step-by-step derivation + Socratic discussion	Uncertain derivation path
verify	"verify derivation"	Verification report + correction suggestions	Existing derivation needs validation
quick	"compute symbolically"	CAS output + LaTeX only	Fast symbolic computation
explore	"explore constitutive"	Multi-model comparison derivation	Constitutive model selection
journal	"journal quality"	Journal-quality derivation document	Publication-level