# PolymathPlus Error Fixing Guide

## Purpose

This guide helps users and AI agents repair PolymathPlus source after precheck validation reports an error.

Primary objective:

Help students and engineers move from natural-language problem statements to valid PolymathPlus source without inventing unsupported syntax or silently changing the mathematical model.

Use this guide for repair workflow. Use the detailed specs for exact syntax:

- `spec_leq.md`
- `spec_nle.md`
- `spec_deq.md`
- `spec_reg.md`
- `spec_nlp.md`

## Repair Principles

Always:

- Fix the first meaningful validator error before making broad edits.
- Preserve the user's mathematical intent.
- Make the smallest repair that explains the error.
- Keep one singular, fully supported program type.
- Re-run precheck after each repair when a validator is available.

Never:

- Invent required data, guesses, bounds, ranges, or constraints and present them as facts.
- Convert an unsupported problem into PolymathPlus source without an explicit reformulation.
- Build a composite source program that chains multiple program types.
- Add unsupported syntax to satisfy a user request.

## Repair Workflow

1. Read the validator message.
2. Identify the error category.
3. Check the selected program type.
4. Repair only the relevant line or section.
5. Re-run precheck.
6. If the repair needs a modeling assumption, ask the user before generating final source.

## Unsupported Problem Type

Symptoms:

- The user asks for a problem outside LEQ, NLE, DEQ, REG, or NLP.
- The problem requires PDEs, unsupported DAEs, stochastic simulation, symbolic solving, discrete optimization, or another unsupported workflow.

Repair action:

- Do not generate source.
- State that the requested problem type is not directly supported.
- Offer a supported reformulation only if it is mathematically reasonable.
- Ask the user whether to proceed with the reformulation.

Recommended response:

```txt
PolymathPlus does not directly support this problem type. It supports LEQ, NLE, DEQ, REG, and NLP. I can help reformulate the problem into a supported type if you provide or approve the reformulation.
```

## Composite Or Multi-Stage Workflow

Symptoms:

- The request needs one solve result to feed another solve.
- The source would need to combine LEQ and DEQ, REG and NLP, or another chain of program types.

Repair action:

- Do not create one composite source file.
- Explain that PolymathPlus precheck expects one identifiable program type per source program.
- Ask which single stage to generate first.

Recommended response:

```txt
This is a multi-stage workflow. A single PolymathPlus source program must use one singular program type, so I cannot generate one file that solves both stages. Tell me which stage to generate first.
```

## Unknown Variable

Symptoms:

- Validator reports an unknown variable.
- A variable is used in an expression but is not defined by the selected program type's rules.

Repair action:

- Check spelling first.
- Define a missing known constant or helper equation.
- Add a required guess, bound, initial value, range, or table column only when the value is already supplied, clearly a typo correction, or explicitly approved by the user.
- Ask the user if the missing value is a modeling input.

Do not guess unknown physical constants or initial conditions unless the user explicitly accepts the assumption.

## Duplicate Definition

Symptoms:

- A variable is defined more than once.
- A variable appears both as an explicit variable and as a model variable.
- A table header contains a duplicate name.

Repair action:

- Keep one definition when the duplicate is accidental.
- Rename only when the names refer to distinct concepts.
- For duplicate table headers, correct the header and row meanings together.

## Mixed Program Styles

Symptoms:

- A table appears with differential equations.
- A regression command appears with `min:`.
- A DEQ derivative appears with NLE root equations.
- Linear equations are mixed with nonlinear assignment syntax.

Repair action:

- Choose one program type.
- Remove syntax from other program types.
- If the real workflow has multiple stages, generate only one stage at a time.

## Invalid Or Incomplete Table

Symptoms:

- Duplicate table headers.
- A numeric row has too few or too many columns.
- Non-numeric table cell.
- Multiple table blocks.

Repair action:

- Keep exactly one table when the selected program type uses a table.
- Make every row match the header column count by correcting supplied data, not by inventing missing cells.
- Use unique valid variable names in the header.
- Keep table data numeric.
- Do not invent table columns, cells, or rows to satisfy row/header counts.

## Missing Required Inputs

Symptoms:

- NLE1 missing bounds.
- NLES missing initial guesses.
- DEQ missing initial values, final value, or independent-variable range.
- REG `nlinfit` missing parameter guesses.
- NLP missing guess/bounds lines.
- NLP `fit:` missing one data table, measured dependent column, or required table data.

Repair action:

- Ask for the required input if it is not supplied.
- If a heuristic starting value is reasonable, label it as a guess and ask for approval.
- Generate final source only after the input is supplied or the assumption is explicitly accepted.

## NLE Repairs

For NLE1:

- Use one `f(variable)` root equation.
- Provide required bounds for the root variable.

For NLES:

- Use one `f(variable)` root line per nonlinear variable.
- Provide one initial guess per nonlinear variable.
- Do not invent missing guesses as known data.
- If constrained guess syntax such as `>0` or `>=0` is used, follow `spec_nle.md`; do not add or remove constrained-mode directives without preserving the user's intended bounds.

For expression evaluation:

- Use explicit equations only.
- Remove root bounds or guesses unless the selected NLE subtype requires them.

## DEQ Repairs

Common repairs:

- Keep one derivative notation style.
- Provide initial values for differential variables.
- Provide a final value or range for the independent variable.
- Do not assign an independent-variable range to a differential variable.
- Break circular explicit helper equations.

Use `spec_deq.md` for exact derivative and initial/final syntax.

## REG Repairs

Common repairs:

- Keep one table and one command.
- Use `polyfit`, `mlinfit`, `nlinfit`, or `integrate`.
- For `nlinfit`, use `m(parameter)=guess` for fitted parameter guesses.
- Ensure `nlinfit` guesses match fitted model parameters exactly.
- Do not use NLP `fit:` syntax for ordinary REG fitting.

Use REG for ordinary table-based fitting before considering NLP `fit:`.

## NLP Repairs

Common repairs:

- Keep exactly one `min:` or NLP `fit:` statement.
- Add guess/bounds lines for model variables.
- Keep guesses inside bounds.
- For NLP `fit:`, ensure exactly one valid table is present.
- If NLP `fit:` data are missing, ask instead of fabricating rows.
- Convert equality constraints to residual form: `residual = 0`.
- Convert inequality constraints to residual form: `residual > 0`.
- Do not use `>=`, `<=`, or nonzero inequality right-hand sides.
- For a model variable constrained to zero, prefer `x - 0 = 0` instead of bare `x = 0`.

Ask for clarification if a constraint cannot be written in supported residual form without changing the model.

## Circular Dependency

Symptoms:

- A helper equation depends on itself.
- Two or more helpers form a dependency loop.

Repair action:

- Break the loop only by algebraically rewriting the stated model or using a value already provided by the problem.
- If breaking the loop requires a new modeling assumption, ask the user.

## Valid Repair Prompt

Use this prompt when asking an AI agent to repair source:

```txt
The following PolymathPlus source failed precheck.
Repair it while preserving the mathematical intent.
Do not invent missing inputs.
If a required modeling value is missing, ask for it instead of generating final source.
Output only the corrected source if repair is possible.

Source:
<paste source>

Validator messages:
<paste messages>
```

## Final Check Before Solving

Before solving, confirm:

- The source is one singular supported program type.
- Required inputs are present.
- There are no unknown variables.
- There are no duplicate definitions.
- There are no unsupported constraints or mixed syntax.
- Precheck passes when a validator is available.