AI Agent Reference

This page provides a structured, machine-readable summary of the Modellus system for AI agents that generate, interpret, or modify Modellus models.

Schema Files

Canonical references for model structure and expression syntax:

Schema	Purpose
Model Schema	Full model JSON structure: shapes array, properties, visualization settings
Expression Schema	Expression language grammar: statements, operators, functions, AST nodes

Shape Types

Type ID	Class	Purpose	Parent Required
expression	ExpressionShape	Define equations, parameters, ODEs, recurrences	No
table	TableShape	Display/enter data, perform regression	No
chart	ChartShape	Plot data series and regression curves	No
body	BodyShape	Animated sprite controlled by terms	Referential
point	PointShape	Positioned dot driven by X/Y terms	Referential
line	LineShape	Segment between two coordinate pairs	Referential
arc	ArcShape	Curved segment / angle indicator	Referential
vector	VectorShape	Arrow with direction and magnitude	Referential
slider	SliderShape	Interactive parameter control	No
gauge	GaugeShape	Circular meter display	No
value	ValueShape	Numeric readout of a term	No
media	MediaShape	Image / background	No
text	TextShape	Rich text annotation	No
ruler	RulerShape	Distance measurement tool	No
protractor	ProtractorShape	Angle measurement tool	No
referential	ReferentialShape	Coordinate system container	No
question	QuestionShape	Assessment question	No

Expression Language Summary

Statement Types

Kind	Pattern	Term Type
function	`name = expr`	PARAMETER (no dependencies) or FUNCTION
differential	`\frac{dx}{dt} = expr`	DIFFERENTIAL
functionSubscript	`x_{n} = expr`	RECURRENCE
functionSubscriptDigit	`x_0 = expr`	PARAMETER
functionIndependent	`f(t) = expr`	FUNCTION
conditional	`name = \begin{cases}...\end{cases}`	FUNCTION
display	`expr` (no assignment)	None (visual only)

Built-in Functions

Trig:      \sin, \cos, \tan, \cot, \sec, \csc
Inv Trig:  \arcsin, \arccos, \arctan
Hyperbolic: \sinh, \cosh, \tanh
Log:       \ln, \log
Two-arg:   \max(a,b), \min(a,b), \mod(a,b)
Utility:   sign(x), rnd(x), irnd(x), int(x), round(x)
Other:     \det(x), \sqrt{x}

Operators

Arithmetic: +  -  \cdot  /  \frac{}{}  ^{}  \sqrt{}
Comparison: =  >  <  \ge  \le  \neq
Logical:    \lor (OR)  \land (AND)
Special:    \Delta (finite difference)

Constants

\pi = 3.14159...
e (or \E) = 2.71828...

Model JSON Structure

{
  "properties": {
    "independent": { "name": "t", "start": 0, "end": 10, "step": 0.1 },
    "initialValuesByCase": { "1": { "x": 0, "v": 5 } }
  },
  "shapes": [
    {
      "type": "expression",
      "id": "uuid",
      "expression": "\\displaylines{g=9.8\\\\\\frac{dx}{dt}=v}",
      "position": { "x": 100, "y": 100 }
    },
    {
      "type": "referential",
      "id": "uuid",
      "children": [
        { "type": "point", "id": "uuid", "xTerm": "x", "yTerm": "y" }
      ]
    }
  ]
}

Key Rules for Agents

Term names must be globally unique across all Expression shapes in a model
Differential equations require initial values in properties.initialValuesByCase
Second-order ODEs must be decomposed into two first-order ODEs
All function calls use \left( and \right) delimiters
Explicit multiplication uses \cdot — the × symbol is not in the grammar
Positional child shapes (Point, Body, Vector, Line, Arc) require a Referential parent
The expression field stores LaTeX in a \displaylines{} wrapper with \\ line separators
Data columns in Tables produce terms of type DATA
Regression results produce terms of type REGRESSION

For the complete formal grammar specification, see the Expression Schema page.