/matlab-symbolic-math

name: matlab-symbolic-math
description: Generate correct MATLAB code using the Symbolic Math Toolbox. Use when the user asks for symbolic computations, analytical solutions, symbolic differentiation/integration, equation solving, or converting symbolic results to numeric MATLAB functions. Also use when converting differential equations to transfer functions or state-space form.
license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata:
  author: MathWorks
  version: "1.0"

MATLAB Symbolic Math Toolbox

This skill provides guidelines, correct syntax, and common patterns for generating MATLAB® code that uses Symbolic Math Toolbox.

When to Use This Skill

• Creating or manipulating symbolic variables, expressions, and functions
• Performing symbolic differentiation, integration, limits, or summation
• Simplifying, factoring, expanding, or collecting symbolic expressions
• Computing Laplace, Fourier, or Z-transforms and their inverses
• Deriving transfer functions or state-space equations from differential equations
• Displaying or plotting symbolic expressions
• Using variable precision arithmetic (VPA)
• Generating MATLAB functions, Simulink function blocks, Simscape equations, and C code from symbolic expressions

Critical Rules

1. NEVER Pass Strings or Character Vectors to Symbolic Functions

**WRONG (deprecated — warns today, errors in a future release; the single `=` in `solve` errors now):**

solve('x^2 + 2*x - 3 = 0')
dsolve('Dy = -a*y')

**CORRECT:**

syms x
solve(x^2 + 2*x - 3 == 0, x)

syms y(t) a
dsolve(diff(y,t) == -a*y)

2. Use `syms` for Interactive Work, `sym` for Functions and Constants

• **`syms x y z`** — Creates fresh symbolic variables and clears any prior assumptions. Use for interactive scripts and Live Scripts.
• **`x = sym('x')`** — Refers to a symbolic variable. Inherits existing assumptions. Required inside MATLAB functions (not scripts) because `syms` dynamically creates workspace variables.
• **`sym(pi)`** — Converts numeric to exact symbolic. Use for symbolic constants.
• **`sym('pi')`** — Creates a symbolic *variable named* `pi`, NOT the mathematical constant π. This is a common source of confusion.

**WRONG:**

% Inside a function:
function result = myFunc()
    syms x          % Error or unreliable in compiled/nested functions
    result = x^2;
end

% Creating symbolic constant pi:
p = sym('pi');      % Creates variable named "pi", NOT the constant

**CORRECT:**

% Inside a function:
function result = myFunc()
    x = sym('x');   % Use sym inside functions
    result = x^2;
end

% Creating symbolic constant pi:
p = sym(pi);        % Converts numeric pi to exact symbolic π

3. Assumption Management

Assumptions persist in the symbolic engine even after `clear`. This is a frequent source of subtle bugs.

% Setting assumptions
syms x real                  % x is real (clears prior assumptions)
syms n positive integer      % n is a positive integer
assume(x > 0)                % x is positive (REPLACES all prior assumptions on x)
assumeAlso(x < 10)           % ADDS assumption: 0 < x < 10

% Checking assumptions
assumptions(x)               % Shows assumptions on x
assumptions                  % Shows ALL assumptions in workspace

% Clearing assumptions — THREE ways (know the differences):
syms x                       % Recreate with syms: clears assumptions
assume(x, 'clear')           % Explicitly clear assumptions on x
reset(symengine)             % Nuclear option: clears EVERYTHING

% DANGER: clear x does NOT clear assumptions!
clear x                      % Removes variable from workspace
x = sym('x');                % x INHERITS old assumptions from engine!

**Best Practice:** Use `syms` to create variables at the start of a script. This clears stale assumptions. Use `assume(x, 'clear')` when you need to reset a specific variable mid-script.

4. `subs` Does Not Modify In-Place

The `subs` function returns a new expression. It does NOT modify the original.

**WRONG:**

syms x
f = x^2 + 3*x;
subs(f, x, 2);         % Result is discarded!
disp(f)                % Still x^2 + 3*x

**CORRECT:**

syms x
f = x^2 + 3*x;
f_val = subs(f, x, 2);    % Assign the result
% or: f = subs(f, x, 2);  % Overwrite f

5. Do Not Wrap Numeric Literals in `sym()` Inside Symbolic Expressions

AI tools frequently over-wrap every numeric literal in `sym()`. When any operand in an arithmetic expression is symbolic, MATLAB automatically promotes all numeric literals in that expression to symbolic. Wrapping literals in `sym()` adds clutter and can cause errors. **When you DO need `sym()`:** Only when creating a standalone symbolic number with NO symbolic variables present in the expression.

% No symbolic variable involved — sym() IS needed:
half = sym(1/2);                % Exact 1/2, not 0.5 double
half = sym(1)/2;                % Exact 1/2, declaring sym(1) promotes all numeric literals to symbolic
piExact = sym(pi);              % Exact π, not 3.14159...

% Symbolic variable already present — sym() is NOT needed:
syms x
f = x/2 + 1/3;                 % Automatically exact: x/2 + 1/3
g = exp(-x^2/2) / sqrt(2*pi);  % All literals promoted by x

6. Variable Naming: Symbolic-to-Numeric Conversions

When substituting numeric values or converting symbolic expressions to numeric form, keep the base variable name and append a suffix indicating the conversion type:

• **`Val`** — after `subs()` or `double()` (numeric value)
• **`Vpa`** — after `vpa()` (variable-precision arithmetic)

syms m g L

% Substituting numeric values
mVal = double(subs(m, 5));         % or: mVal = 5;
gVal = 9.81;
LVal = 0.5;

% Evaluating a symbolic expression numerically
omega = sqrt(g/L);
omegaVal = double(subs(omega, [g L], [gVal LVal]));

% Variable-precision arithmetic
piVpa = vpa(sym(pi), 50);
omegaVpa = vpa(subs(omega, [g L