External Algorithm Repository Template

This is a template for creating external algorithm repositories compatible with the CPPModel algorithm loader.

Repository Structure

my-algorithms/
├── README.md
├── CONTRIBUTING.md
├── algorithms.json          # Registry of all algorithms
├── schema/
│   └── algorithm.schema.json
└── algorithms/
    ├── my-controller/
    │   ├── definition.json
    │   ├── cyclic.ts
    │   ├── docs.md
    │   └── templates/
    │       ├── c.template
    │       └── cpp.template
    └── my-plant/
        └── ...

Quick Start

1. Fork this repository
2. Add your algorithm in algorithms/your-algorithm-name/
3. Register it in algorithms.json
4. Submit a pull request

Loading Algorithms

Algorithms can be loaded from GitHub:

import { algorithmRegistry } from '@/algorithms';

// Load from GitHub repository
await algorithmRegistry.loadFromGitHub('username/repo-name');

// Load specific algorithm from URL
await algorithmRegistry.loadFromUrl('https://raw.githubusercontent.com/user/repo/main/algorithms/my-controller/');

Algorithm Requirements

1. Definition File (definition.json)

{
  "id": "unique-algorithm-id",
  "name": "Algorithm Display Name",
  "shortName": "Short",
  "description": "Brief description of the algorithm",
  "category": "controller",
  "complexity": "intermediate",
  "simulationMode": "closed-loop",
  "plantId": "first-order-plant",
  "parameters": [...],
  "tags": ["control", "feedback"]
}

2. Cyclic Function (cyclic.ts)

Must be a pure function with no side effects:

export function cyclic(
  params: Record<string, number>,
  inputs: { setpoint: number; feedback?: number },
  state: { output: number; [key: string]: unknown } | null,
  dt: number
): { output: number; [key: string]: unknown } {
  // Your algorithm logic here
  return { output: computedValue, ...newState };
}

3. Documentation (docs.md)

Markdown documentation explaining:

• Algorithm theory
• Parameters description
• Usage examples
• References

4. Code Templates (templates/)

C and C++ templates for embedded export.

Security Constraints

For security, algorithms must:

• ✅ Be pure functions (deterministic, no side effects)
• ✅ Use only basic math operations
• ❌ No eval, Function, setTimeout, setInterval
• ❌ No fetch, XMLHttpRequest, network access
• ❌ No window, document, localStorage access
• ❌ No require, import statements
• ❌ No infinite loops (execution time limited)

License

Algorithms in this repository are licensed under MIT unless otherwise specified.