> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Toolbox for Hard Maths

> A guide to solving complex mathematical problems in Calcs.com templates

When facing complex mathematical challenges in template development, you have several powerful tools at your disposal. This guide helps you choose the right approach for your specific problem.

## Existing MathJS Functions

It's always worth triple-checking what *already exists* in the [MathJS Functions Reference](https://mathjs.org/docs/reference/functions.html).

<Note>
  Some functions have unexpected names - for example, `compareNatural()` can do matrix comparisons. Always search thoroughly!
</Note>

### Pros

* No new code required
* More functions exist than you probably think!
* Well-tested and documented

### Cons

* Sometimes weird or hard-to-read function names (add a description or authorNote!)
* Can be awkward making a function work that isn't quite intended for your use case
* Your specific solution may not exist

### Best Suited For

Being your first port of call for mild-to-moderate complexity problems.

## Temporary Custom Functions

MathJS allows you to define temporary custom functions within your templates.

### Pros

* Programming with no dev help required 🙂
* Particularly useful when creating or processing matrices
* Works across multiple widgets in the same template

### Cons

* Limited to MathJS capabilities
* Doesn't render correctly in LaTeX (can be fixed if needed)

### Best Suited For

Doing weird manipulation of matrices or creating simple custom operations.

### Examples

<CodeGroup>
  ```javascript "Matrix Manipulation" theme={null}
  map(my_matrix, f(value, index, the_matrix) = value + the_matrix[index+1])
  ```

  ```javascript "Combination Function" theme={null}
  comb(n,r) = n! / ((n-r)! * r!); 
  comb(6,3)
  ```
</CodeGroup>

<Tip>
  Custom functions DO work over multiple widgets! Define once, use anywhere in the template.
</Tip>

## Permanent Custom Functions

We have existing custom functions like `iterate()`, `interpolate()`, and more. New ones can be added as needed.

### Pros

* Very fast (executed in users' web browsers)
* Can use both MathJS and native JavaScript libraries
* Minimal code required
* No network latency

### Cons

* Engineers may be less familiar with JavaScript
* Not well suited for calling external libraries or APIs
* Bad for memory-intensive work (e.g., huge matrices)

### Best Suited For

Operations that require less than \~5 parameters of data and nothing outside MathJS or native JavaScript.

### Existing Custom Functions

* `iterate()` - Iterative solving
* `interpolate()` - Linear and non-linear interpolation
* `solveSecant()` - Secant method solver
* [See full documentation](#)

## Python Solvers

The big Python scripts that handle complex engineering calculations.

### Pros

* Lots of external libraries available (check licenses for commercial use!)
* Python is similar to Matlab and familiar to engineers
* Few restrictions on memory or CPU
* Can handle complex FEA and matrix operations

### Cons

* Every solver call requires a network roundtrip (\~100-300ms each)
* Must always support history - hard to change once written
* Requires careful consideration to write good-quality code

### Best Suited For

Super-complex calculations:

* Finite Element Analysis (FEA)
* Huge matrices
* External library dependencies
* API integrations

<Warning>
  Solver calls add up quickly! Each call is 100-300ms, so minimize the number of calls in your template.
</Warning>

## Decision Tree

```mermaid theme={null}
graph TD
    A[Complex Math Problem] --> B{Can MathJS handle it?}
    B -->|Yes| C[Use Existing MathJS]
    B -->|No| D{Need matrices/loops?}
    D -->|Yes| E{Simple manipulation?}
    E -->|Yes| F[Temporary Custom Function]
    E -->|No| G{Need external libs?}
    D -->|No| G
    G -->|No| H[Permanent Custom Function]
    G -->|Yes| I{Heavy computation?}
    I -->|Yes| J[Python Solver]
    I -->|No| H
```

## Performance Considerations

<Cards>
  <Card title="Browser Functions" icon="bolt">
    **Fastest** (\~1ms)

    * MathJS functions
    * Custom JavaScript functions
    * No network latency
  </Card>

  <Card title="Solver Calls" icon="server">
    **Slowest** (100-300ms)

    * Network roundtrip required
    * Server processing time
    * Use sparingly
  </Card>
</Cards>

## Best Practices

1. **Start Simple**: Always check if MathJS already has what you need
2. **Minimize Solver Calls**: Batch operations when possible
3. **Document Complex Functions**: Add descriptions and author notes
4. **Consider User Experience**: Balance accuracy with performance
5. **Test Edge Cases**: Ensure your solution handles all scenarios

## Getting Help

* Check existing functions documentation
* Ask in engineering Slack channels
* Review similar templates for inspiration
* Consult with dev team for custom function needs