# symbolic pack

19 nodes, in `noodlelab[maths]` and above.

## Symbolic

(node-symbolic.differentiate)=
### Differentiate

`symbolic.differentiate`

The derivative with respect to ``variable``, ``order`` times.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr` |  |
| `variable` | `str` | Default `'x'`. |
| `order` | `int` | Default `1`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Expr` |  |

(node-symbolic.equation)=
### Equation

`symbolic.equation`

An equation, ``lhs = rhs``, for Solve and Solve ODE. Primes are
derivatives: ``y''(x)`` is d²y/dx². Without ``=``, the expression equals zero.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `text` | `str` | SymPy notation: w*L^2/12, sqrt(x), sin(2 pi f t). Juxtaposition multiplies (2 x, E I). E and I are symbols; e is Euler's number. {a} … {d} insert linked expressions. Other constants (c, g0, k_B...) are symbols until a Values line names them: g = g0. Default `"E*I*y''''(x) = -w"`. |
| `a` | `Expr \| None` | Optional. |
| `b` | `Expr \| None` | Optional. |
| `c` | `Expr \| None` | Optional. |
| `d` | `Expr \| None` | Optional. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Equality` |  |

(node-symbolic.equations)=
### Equations

`symbolic.equations`

Several equations, one per line, to be solved together with Solve
System or Solve Numerically, or written as a matrix with Linear System:
one balance equation per mass of a structure, say. Lines starting with
``#`` are comments.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `text` | `str` | SymPy notation: w*L^2/12, sqrt(x), sin(2 pi f t). Juxtaposition multiplies (2 x, E I). E and I are symbols; e is Euler's number. {a} … {d} insert linked expressions. Other constants (c, g0, k_B...) are symbols until a Values line names them: g = g0. One equation per line. Default `'x + y = 3\nx - y = 1'`. |
| `a` | `Expr \| None` | Optional. |
| `b` | `Expr \| None` | Optional. |
| `c` | `Expr \| None` | Optional. |
| `d` | `Expr \| None` | Optional. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `EquationSystem` |  |

(node-symbolic.evaluate)=
### Evaluate

`symbolic.evaluate`

Put numbers with units into an expression. Units are carried through,
so the result has the right dimension: a moment from kN/m and m comes out
in kN·m. An array value (a quantity holding many numbers) gives an array.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr` |  |
| `values` | `SymbolValues` |  |
| `unit` | `str` | Unit of the result; empty: worked out Default `''`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Quantity` |  |

(node-symbolic.evaluate_matrix)=
### Evaluate Matrix

`symbolic.evaluate_matrix`

Put numbers with units into a symbolic matrix, such as the stiffness
matrix from Linear System, for the matrix nodes. A matrix has one unit
for every entry: entries that come out in different units are an error
(zeros fit any unit). Values with uncertainties are used at their nominal
values, since a matrix carries none: use Monte Carlo to propagate them.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `matrix` | `Expr` |  |
| `values` | `SymbolValues` |  |
| `unit` | `str` | Unit of every entry; empty: worked out Default `''`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Quantity` |  |

(node-symbolic.evaluate_range)=
### Evaluate Over Range

`symbolic.evaluate_range`

Evaluate an expression at evenly spaced values of one variable, such as
the deflection along a beam. ``peak`` is the value largest in size (with
its sign) and ``peak_at`` where it occurs. Array quantities plot through
Magnitude (Array). Complex values, which have no order, are ranked by
their size |y|: ``minimum`` and ``maximum`` are then the smallest and the
largest in size.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr` |  |
| `values` | `SymbolValues` |  |
| `variable` | `str` | Default `'x'`. |
| `start` | `str` | An expression in the values: 0, L/2 Default `'0'`. |
| `stop` | `str` | An expression in the values: L Default `'L'`. |
| `points` | `int` | Default `201`. |
| `unit` | `str` | Unit of the result; empty: worked out Default `''`. |
| `variable_unit` | `str` | Unit of x; empty: that of start Default `''`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `x` | `Quantity` |  |
| `value` | `Quantity` |  |
| `peak` | `Quantity` |  |
| `peak_at` | `Quantity` |  |
| `minimum` | `Quantity` |  |
| `maximum` | `Quantity` |  |

(node-symbolic.expression)=
### Expression

`symbolic.expression`

A symbolic expression typed as text. Names that are not functions
become symbols; ``{a}`` … ``{d}`` insert the linked expressions, so
``-E*I*diff({a}, x, 2)`` differentiates whatever is linked to a.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `text` | `str` | SymPy notation: w*L^2/12, sqrt(x), sin(2 pi f t). Juxtaposition multiplies (2 x, E I). E and I are symbols; e is Euler's number. {a} … {d} insert linked expressions. Other constants (c, g0, k_B...) are symbols until a Values line names them: g = g0. Default `'w*L^2/12'`. |
| `a` | `Expr \| None` | Optional. |
| `b` | `Expr \| None` | Optional. |
| `c` | `Expr \| None` | Optional. |
| `d` | `Expr \| None` | Optional. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Expr` |  |

(node-symbolic.to_math)=
### Expression To Math

`symbolic.to_math`

Typst math for the report's Add Equation node: the expression as it
would be typeset, optionally as ``left = expression``. A system of
equations is typeset one equation per line.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr \| Equality \| EquationSystem` |  |
| `left` | `str` | Optional left-hand side, e.g. M(x) or sigma_max Default `''`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `str` |  |

(node-symbolic.integrate)=
### Integrate

`symbolic.integrate`

The integral with respect to ``variable``: indefinite (without a
constant), or between two limits, which may be symbols such as 0 and L.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr` |  |
| `variable` | `str` | Default `'x'`. |
| `lower` | `str` | Empty for an indefinite integral Default `''`. |
| `upper` | `str` | Empty for an indefinite integral Default `''`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Expr` |  |

(node-symbolic.iterate)=
### Iterate

`symbolic.iterate`

Repeat a step until the answer stops changing: a while loop in one node.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr \| Equality` |  |
| `values` | `SymbolValues \| None` | Optional. |
| `variable` | `str` | Default `'x'`. |
| `method` | `Literal['fixed point', 'newton']` | Default `'fixed point'`. |
| `start` | `str` | The first guess, an expression in the values: 0.02, L/2 Default `'1'`. |
| `digits` | `int` | Stop when a pass changes x by less than 10^-digits of x Default `10`. |
| `max_iterations` | `int` | Default `100`. |
| `unit` | `str` | Unit of the result; empty: worked out Default `''`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Quantity` |  |
| `iterations` | `int` |  |
| `converged` | `bool` |  |
| `step` | `NDArray[float64]` |  |
| `history` | `NDArray` |  |
| `change` | `NDArray[float64]` |  |

(node-symbolic.linear_system)=
### Linear System

`symbolic.linear_system`

Write linear equations as a matrix equation, A x = b, with x the
unknowns in the order given: the equilibrium of masses on springs gives
the stiffness matrix K and the force vector F. Evaluate Matrix puts
numbers into both, and Solve Linear System solves it.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `equations` | `EquationSystem \| Equality` |  |
| `unknowns` | `str` | The unknowns, comma separated: x1, x2 Default `'x1, x2'`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `A` | `ImmutableDenseMatrix` |  |
| `b` | `ImmutableDenseMatrix` |  |
| `unknowns` | `list[str]` |  |

(node-symbolic.set_value)=
### Set Value

`symbolic.set_value`

Add a linked value (a quantity or a number from elsewhere in the graph)
to a set of values, under ``name``.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `values` | `SymbolValues \| None` | Optional. |
| `name` | `str` | Default `'x'`. |
| `value` | `Quantity \| float` | Default `0.0`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `SymbolValues` |  |

(node-symbolic.simplify)=
### Simplify

`symbolic.simplify`

Rewrite an expression: simplify (SymPy's heuristics), factor, expand
products and powers, cancel common factors, put over one denominator
(together), or simplify trigonometric functions.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr` |  |
| `method` | `Literal['simplify', 'factor', 'expand', 'cancel', 'together', 'trigsimp']` | Default `'simplify'`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Expr` |  |

(node-symbolic.solve)=
### Solve

`symbolic.solve`

Solve an equation (or ``expression = 0``) for one unknown, in symbols.
``solution`` is the solution numbered ``pick``, ``solutions`` all of them.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `equation` | `Equality \| Expr` |  |
| `unknown` | `str` | Default `'x'`. |
| `pick` | `int` | Which solution, when there are several Default `0`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `solution` | `Expr` |  |
| `solutions` | `list[Expr]` |  |
| `count` | `int` |  |

(node-symbolic.solve_numeric)=
### Solve Numerically

`symbolic.solve_numeric`

Solve equations, linear or not, numerically for the unknowns that have
a guess, starting from those guesses (SciPy's root). Each unknown comes
out in the unit of its guess. The other symbols take ``values``, whose
uncertainties are propagated to the solutions (GUM).

**Inputs**

| Name | Type | Description |
|---|---|---|
| `equations` | `EquationSystem \| Equality` |  |
| `guesses` | `str` | A first guess for each unknown, with its unit, one per line: x1 = 1 cm Default `'x = 1'`. |
| `values` | `SymbolValues \| None` | Optional. |
| `method` | `Literal['hybr', 'lm']` | hybr: as many equations as unknowns; lm: least squares, more is fine Default `'hybr'`. |
| `max_iterations` | `int` | Default `1000`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `values` | `SymbolValues` |  |
| `solution` | `Quantity` |  |
| `converged` | `bool` |  |
| `residual` | `float` |  |
| `iterations` | `int` |  |
| `summary` | `dict[str, float]` |  |

(node-symbolic.solve_ode)=
### Solve ODE

`symbolic.solve_ode`

Solve an ordinary differential equation for ``function(variable)``.
With enough conditions the constants of integration are found; without,
they stay as C1, C2, ... The result is the right-hand side, y(x).

**Inputs**

| Name | Type | Description |
|---|---|---|
| `equation` | `Equality` |  |
| `function` | `str` | Default `'y'`. |
| `variable` | `str` | Default `'x'`. |
| `conditions` | `str` | Boundary or initial conditions, comma separated: y(0) = 0, y'(L) = 0 Default `''`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Expr` |  |

(node-symbolic.solve_system)=
### Solve System

`symbolic.solve_system`

Solve several equations together for several unknowns, in symbols.
``answers`` shows them all (x1 = …, x2 = …), ``solution`` is one of them
for Evaluate, and ``solutions`` is the column of all of them, in the order
of ``unknowns``. An unknown the equations leave free stays a symbol.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `equations` | `EquationSystem \| Equality` |  |
| `unknowns` | `str` | The unknowns, comma separated: x1, x2 Default `'x1, x2'`. |
| `unknown` | `str` | The unknown that solution gives, such as x2; empty: the first Default `''`. |
| `pick` | `int` | Which solution, when there are several (from 0) Default `0`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `answers` | `EquationSystem` |  |
| `solution` | `Expr` |  |
| `solutions` | `ImmutableDenseMatrix` |  |
| `count` | `int` |  |

(node-symbolic.substitute)=
### Substitute

`symbolic.substitute`

Replace symbols by expressions: ``x = L/2`` gives the value at mid-span,
still in symbols. To put in numbers with units, use Evaluate.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `expression` | `Expr` |  |
| `substitutions` | `str` | name = expression; one per line or ; separated Default `'x = L/2'`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `Expr` |  |

(node-symbolic.values)=
### Values

`symbolic.values`

Numbers, usually with units, for the symbols of an expression. A value
without a unit is a plain number. A value can also name a constant, with
its unit and uncertainty: ``g = g0`` is standard gravity, and a line that
is just a name, such as ``c``, means ``c = c``. Constants are looked up
before units, so ``h`` is Planck's constant here, not an hour: write
``t = 1 h`` for an hour. A name that means something else as a unit is
flagged with a warning.

**Inputs**

| Name | Type | Description |
|---|---|---|
| `text` | `str` | name = value with a unit, one per line: E = 200 GPa, L = 6 m, n = 3. A constant by name: g = g0, or just the line c Default `'E = 200 GPa\nL = 6 m'`. |

**Outputs**

| Name | Type | Description |
|---|---|---|
| `result` | `SymbolValues` |  |