# PolymathPlus DEQ Specification

## What This Program Type Solves

DEQ is the PolymathPlus differential-equation program type. It solves initial-value ordinary differential equations, including systems of ODEs, with optional explicit helper equations.

Common rules that always apply:

- `#` starts a comment. Comments are ignored by validation.
- Blank lines are allowed and ignored.
- Variable names must start with a letter and then use only letters, digits, or underscore.
- Avoid built-in function names or conditional keywords as variable names. Examples to avoid include `sin`, `sqrt`, `log`, `if`, `then`, and `else`. The left side of some DEQ lines may still pass precheck with these names, but expression use will be tokenized as functions or conditional keywords.
- Also avoid variable names that begin with `and` or `or`, because those prefixes are tokenized as logical operators by the validator when used in expressions.
- Keep one consistent program style. Do not mix DEQ with LEQ, NLE, NLP, regression, or table-based program formats.

## User Rules For Writing A Valid DEQ Program

### 1. Use a supported derivative-line format

Supported derivative-line formats:

```polymathplus
d(x)/d(t) = expression
dx/dt = expression
x' = expression
```

Rules:

- The right-hand side must be a valid math expression.
- Each differential variable can be defined only once.
- If you use `d()/d()` notation, the derivative line must be fully parenthesized or fully compact.
- Mixed derivative notation such as `d(x)/dt` is invalid.
- Prime notation such as `x' = ...` is accepted, but the independent variable is inferred from the independent-variable final/range definition. With prime notation, provide exactly one independent-variable range/final definition such as `t|0:3` or `t(0)=0` plus `t(f)=3`.
- Do not use `var|start:end` for a differential variable. The `|start:end` form belongs to the independent variable only.

Invalid mixed derivative notation:

```polymathplus
d(T)/dt = -k*T
k = 1
T(0) = 1
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(T)/d(t) = -k*T
k = 1
T(0) = 1
t(0) = 0
t(f) = 2
```

### 2. Use one independent variable

All derivative lines must use the same independent variable.

Valid:

```polymathplus
d(A)/d(t) = -k*A
d(B)/d(t) = k*A
A(0) = 1
B(0) = 0
t(0) = 0
t(f) = 5
```

Invalid mixed independent variables:

```polymathplus
d(A)/d(t) = -A
d(B)/d(x) = -B
A(0) = 1
B(0) = 1
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -A
d(B)/d(t) = -B
A(0) = 1
B(0) = 1
t(0) = 0
t(f) = 2
```

### 3. Explicit-equation rules

Explicit equations use this format:

```polymathplus
variable = expression
```

Rules:

- Explicit equations are allowed in DEQ programs.
- Use explicit equations to simplify long derivative formulas or reuse repeated terms.
- Explicit variable names must be unique.
- Explicit variables must not be circular or self-referencing.
- An explicit variable cannot use the same name as a differential variable.
- The independent variable cannot also be an explicit variable.

Valid helper equations:

```polymathplus
q1 = W*Cp*(T0-T1)+UA*(Tsteam-T1)
q2 = W*Cp*(T1-T2)+UA*(Tsteam-T2)
d(T1)/d(t) = q1/(M*Cp)
d(T2)/d(t) = q2/(M*Cp)
T1(0) = 20
T2(0) = 20
t(0) = 0
t(f) = 200
```

Invalid explicit/differential overlap:

```polymathplus
d(A)/d(t) = -A
A = 2
A(0) = 1
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 0
t(f) = 2
```

Invalid independent variable as explicit variable:

```polymathplus
d(A)/d(t) = -A
t = 0
A(0) = 1
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 0
t(f) = 2
```

### 4. Initial-value rules

Every differential variable needs exactly one initial value.

Supported initial-value formats:

```polymathplus
x(0) = number
x|number
```

Rules:

- Initial values must be numeric literals, not expressions.
- Do not define the same initial value more than once for the same variable.
- Do not provide initial values for unknown variables.

Invalid duplicate initial value:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
A|2
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 0
t(f) = 2
```

Invalid initial value expression:

```polymathplus
d(A)/d(t) = -A
A(0) = 1 + 1
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -A
A(0) = 2
t(0) = 0
t(f) = 2
```

### 5. Independent-variable initial/final/range rules

The independent variable must have an initial value and a final value. The final value must be greater than the initial value.

Supported formats:

```polymathplus
t(0) = number
t(f) = number
t|start:end
```

Rules:

- Only the independent variable can use `(f)` or `|start:end`.
- Final/range values must be numeric literals, not expressions.
- Keep only one final/range definition for the independent variable.
- Do not assign a final value or range to a differential variable.

Valid range syntax:

```polymathplus
A' = -k*A
k = 1
A|1
t|0:3
```

Invalid prime/range usage:

```polymathplus
A' = -k*A
k = 1
A|1:3
t|0:3
```

Repair:

```polymathplus
A' = -k*A
k = 1
A|1
t|0:3
```

Invalid final value on a differential variable:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
A(f) = 2
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 0
t(f) = 2
```

Invalid duplicate final/range definition:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 0
t(f) = 2
t|0:3
```

Repair:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 0
t(f) = 2
```

Invalid final value not greater than initial value:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 2
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -A
A(0) = 1
t(0) = 0
t(f) = 2
```

### 6. Unknown-variable and role-consistency rules

Every variable used in derivative or explicit expressions must be one of:

- a differential variable
- an explicit variable
- the independent variable

Invalid unknown variable:

```polymathplus
d(A)/d(t) = -k*A
A(0) = 1
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -k*A
k = 0.5
A(0) = 1
t(0) = 0
t(f) = 2
```

Invalid circular explicit definitions:

```polymathplus
d(A)/d(t) = -k*A
k = q + 1
q = k + 1
A(0) = 1
t(0) = 0
t(f) = 2
```

Repair:

```polymathplus
d(A)/d(t) = -k*A
k = 0.5
A(0) = 1
t(0) = 0
t(f) = 2
```

### 7. Solver method metadata

Optional DEQ solver method hint:

```polymathplus
#@DEQ_SOLUTION_METHOD_INDEX = 0
```

Known solver/runtime method index values used by PolymathPlus:

- `0`: RKF45
- `1`: RKF56
- `2`: BS
- `3`: Stiff
- `4`: StiffBS

Runtime default when omitted: `0` (`RKF45`).

Precheck note:

- The precheck treats this line as comment/directive metadata.
- The precheck does not currently validate the method index as supported or unsupported.

## Practical Checklist Before Solve

- At least one valid derivative line exists.
- All derivative lines use one independent variable.
- Every differential variable has exactly one numeric initial value.
- The independent variable has a numeric initial value.
- The independent variable has exactly one numeric final/range definition.
- The final value is strictly greater than the initial value.
- Explicit variables are unique and non-circular.
- No explicit variable overlaps a differential variable.
- The independent variable is not also explicit or differential.
- No unknown variables remain in derivative or explicit expressions.

## Examples Of Valid DEQ Programs

### Example A: One ODE using fully parenthesized derivative notation

```polymathplus
d(T)/d(t) = -k*(T - Ta)
k = 0.15
Ta = 25
T(0) = 120
t(0) = 0
t(f) = 20
```

### Example B: Three ODEs using prime notation and pipe syntax

```polymathplus
A' = -k1*A
B' = k1*A - k2*B
C' = k2*B
k1 = 1
k2 = 2
A|1
B|0
C|0
t|0:3
```

### Example C: Two ODEs using compact derivative notation

```polymathplus
dT1/dt = (W*Cp*(T0-T1)+UA*(Tsteam-T1))/(M*Cp)
dT2/dt = (W*Cp*(T1-T2)+UA*(Tsteam-T2))/(M*Cp)
W = 100
Cp = 2.0
T0 = 20
UA = 10
Tsteam = 250
M = 1000
T1(0) = 20
T2(0) = 20
t(0) = 0
t(f) = 200
```

### Example D: Engineering-style ODE system with an explicit rate

```polymathplus
d(CA)/d(t) = -rA
d(CB)/d(t) = rA
rA = k*CA
k = 0.25
CA(0) = 1
CB(0) = 0
t(0) = 0
t(f) = 10
```

## Verification Notes

This hardened repo-local copy was checked against DEQ behavior in:

```polymathplus
C:\dev\js\solver_precheck\solver_precheck.js
C:\dev\js\solver_precheck\solver_precheckTests.js
```

The examples were selected or adapted from the test corpus and validator behavior. Test-only comments were removed, and example variable names/comments were adjusted for documentation use.