# PolymathPlus LLM Guide

## Purpose

This guide helps students and engineers describe a numerical problem in natural language, then have an AI generate valid PolymathPlus source.

Use this file as the entry point for LLM-assisted modeling. Related resources:

- [Examples](examples.md): prompt patterns and valid PolymathPlus source examples
- [Error Fixing Guide](error-fixing-guide.md): repair patterns for validator and solver errors
- [Agent Instructions](agent-instructions.md): operational workflow for coding agents
- [Linear & Explicit Equations Spec](spec_leq.md): linear equations
- [Nonlinear Equations Spec](spec_nle.md): nonlinear equations and expression evaluation
- [Differential Equations Spec](spec_deq.md): ordinary differential equations
- [Regression Spec](spec_reg.md): regression and tabular integration
- [Optimization Spec](spec_nlp.md): nonlinear programming and least-squares optimization

Do not invent syntax from this guide. When exact syntax matters, follow the relevant linked spec file.

## Modeling Workflow

When converting a natural-language problem into PolymathPlus source:

1. Identify the numerical problem type.
2. Extract known constants, unknown variables, equations, tables, initial values, guesses, bounds, and constraints.
3. Choose exactly one PolymathPlus program type.
4. Write the smallest valid source program that represents the model.
5. Run precheck validation.
6. Repair syntax or modeling errors using validator feedback.
7. Solve the validated program.
8. Explain the result in terms of the original problem.

## Program Type Selection

Choose `LEQ` when the problem is a linear algebraic system:

- unknowns appear only to the first power
- unknowns are not multiplied by each other
- every equation is linear

Choose `NLE` when the goal is to evaluate expressions or solve nonlinear equations:

- expression-calculator style helper equations
- one nonlinear root equation
- simultaneous nonlinear root equations

Choose `DEQ` when the problem has ordinary differential equations:

- derivatives such as `d(C)/d(t)` or `C'`
- initial values
- final time or independent-variable range

Choose `REG` when the problem fits tabular data using built-in regression/integration commands:

- `polyfit`
- `mlinfit`
- `nlinfit`
- `integrate`

Choose `NLP` when the problem is optimization:

- table-free minimization with `min:`
- constrained optimization
- least-squares optimization with `fit:` when NLP bounds or constraints are needed

If more than one type seems possible, choose the type by the required top-level syntax: LEQ equations only, NLE `f(variable)` roots or expression evaluation, DEQ derivatives, REG table plus regression/integration command, or NLP `min:`/`fit:` optimization.

## Common Generation Rules

For all program types:

- Use one program type per source file.
- Use `#` for comments.
- Use variable names that start with a letter and contain only letters, digits, and underscores.
- Avoid built-in function names and conditional keywords as variable names.
- Prefer explicit multiplication with `*`.
- Keep examples small unless the real problem requires more detail.
- Do not mix tables, derivatives, regression commands, optimization statements, and root-equation syntax unless the chosen spec allows that combination.

## Modeling Patterns

Linear mass balance:

```polymathplus
2*A + B = 10
A - B = 1
```

Nonlinear single root:

```polymathplus
f(x) = x*log(x/2) + 4*x^2 - 1620
x(min) = 0.1
x(max) = 100
```

Ordinary differential equation:

```polymathplus
d(A)/d(t) = -k*A
k = 0.3
A(0) = 10
t(0) = 0
t(f) = 5
```

Regression from data:

```polymathplus
[
x y
1 2.1
2 4.2
3 8.1
4 16.3
]
polyfit x y 2
```

Optimization:

```polymathplus
min: (x - 2)^2 + (y - 3)^2
x + y - 4 = 0
x| 1 0 10
y| 1 0 10
```

## Prompt Pattern For Manual LLM Use

Use this prompt shape with ChatGPT, Gemini, Claude, Copilot, or another assistant:

```txt
Convert the following problem into valid PolymathPlus source.

First choose the program type: LEQ, NLE, DEQ, REG, or NLP.
Then list the variables, constants, equations, data table, guesses, bounds, and constraints.
Then output only the PolymathPlus source in one code block.
Follow the relevant PolymathPlus spec and do not invent syntax.

Problem:
<paste problem statement>
```

For repair after validation:

```txt
The following PolymathPlus source failed precheck.
Repair it using the validator messages.
Keep the same mathematical intent and output only the corrected source.

Source:
<paste source>

Validator messages:
<paste messages>
```

## Validation And Repair

Always validate generated source before solving.

When validation fails:

- Read the first error message carefully.
- Identify whether the issue is syntax, missing data, unknown variables, duplicate definitions, unsupported program mixing, or invalid bounds/constraints.
- Repair the smallest part of the program that explains the error.
- Re-run validation after every repair.
- Do not change the mathematical model unless the validator error reveals an actual modeling ambiguity.

Common repairs:

- Unknown variable: define it or correct the spelling.
- Duplicate variable: keep only one definition.
- Mixed program styles: choose one program type and remove incompatible syntax.
- Invalid table: fix header names and row column counts.
- Invalid NLP constraint: follow `spec_nlp.md`; write equality constraints as `residual = 0`, inequalities as `residual > 0`, and do not use `>=`, `<=`, or nonzero inequality right-hand sides.
- Missing guesses, bounds, or ranges: add only the required lines for the selected program type, following the relevant `spec_*.md`.
- Circular helper equations: break the dependency loop.

## Documentation Map

Use the detailed specs as the source for exact syntax:

- For linear systems, use `spec_leq.md`.
- For nonlinear equations, use `spec_nle.md`.
- For ODEs, use `spec_deq.md`.
- For regression and integration, use `spec_reg.md`.
- For optimization and least-squares fitting, use `spec_nlp.md`.

Use later repo docs for specialized workflows:

- `agent-instructions.md`: instructions for AI agents generating PolymathPlus source
- `examples.md`: canonical examples grouped by program type
- `error-fixing-guide.md`: validator-message repair patterns