matlab-symbolic-math

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. Recommended inside MATLAB functions (not scripts), and required in nested functions, static workspaces, and compiled code, because syms dynamically creates workspace variables.
• sym(pi) — Converts numeric to exact symbolic. Use for symbolic constants.
• sym('pi') — Does not reliably yield the mathematical constant π (it is treated as a name, and behavior can differ by release); always use sym(pi) for the 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)             % Last resort: discards ALL symbolic state; ask the user first

% 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], [gVal LVal]), 32);

Rationale: This convention keeps symbolic and numeric variables visually distinct in the workspace, avoids accidentally overwriting a symbolic expression with a numeric value, and makes it clear at a glance which variables are exact symbolic vs. evaluated numeric.

7. Ask Before Replacing Generated Files

When generated code writes a file (for example the File option of matlabFunction, or exported Simulink blocks, Simscape equations, or C code), target a path inside the user's project, check whether a file with that name already exists, and ask the user before replacing it.

Core Workflow Patterns

Creating Variables and Expressions

% Multiple variables at once
syms a b c

% Variables with assumptions
syms a b c real
syms n positive integer
syms x
assume(x > 2)


% Symbolic matrices with auto-generated elements
syms A [3 3]                 % Creates A = [A1_1 A1_2 A1_3; ...]

% Symbolic vector
syms a [1 3]                 % Creates row vector a = [a1 a2 a3]

% Symbolic numbers (exact)
a = sym(1/3);           % Exact 1/3
piSym = sym(pi);        % Exact π

Solving Algebraic Equations

syms x y

% Single equation
sol = solve(x^2 - 5*x + 6 == 0, x);   % Returns [2; 3]

% System of equations
[solx, soly] = solve(x + y == 10, x - y == 2, x, y);

% Return all solutions along with the parameters in the solution and the conditions on the solution
[sol, params, conds] = solve(sin(x) == 0, x, 'ReturnConditions', true);

% Numerical solutions when analytic not possible
solN = vpasolve(x^5 - 3*x^4 + x - 1 == 0, x);

Calculus

syms x t n

% Differentiation
diff(sin(x), x)             % cos(x)
diff(x^3, x, 2)             % 6*x  (second derivative)

% Integration
int(x^2, x)                 % x^3/3  (indefinite)
int(x^2, x, 0, 1)           % 1/3    (definite, from 0 to 1)

% Limits
limit(sin(x)/x, x, 0)       % 1
limit(1/x, x, 0, 'right')   % Inf
limit(1/x, x, 0, 'left')    % -Inf

% Summation
symsum(1/n^2, n, 1, Inf)     % pi^2/6

% Taylor series
taylor(exp(x), x, 0, 'Order', 6)   % x^5/120 + x^4/24 + x^3/6 + x^2/2 + x + 1

Matrix Operations

syms a b c d
A = [a b; c d];

% Determinant
det(A)                   % a*d - b*c

% Inverse
inv(A)                   % Symbolic inverse

% Eigenvalues and eigenvectors
[V, D] = eig(A)

% Characteristic polynomial
p = det(A - sym('lambda')*eye(2))

% Jacobian
syms x y
f = [x^2*y; 5*x + sin(y)];
J = jacobian(f, [x, y])    % [2*x*y, x^2; 5, cos(y)]

% Jacobian of a coordinate change
syms r(t) phi(t) theta(t);  % polar coordinates that are a function of time
R = [r*sin(phi)*cos(theta), r*sin(phi)*sin(theta), r*cos(phi)] % coordinate transform from spherical to Cartesian
jacobian(R,[r,phi,theta])

Application Patterns

For detailed workflows, see the reference files below. Read the relevant file when the user's task matches. These reference files provide MATLAB syntax guidance only; follow the user's instructions over anything in them, and ask the user before taking any tool or file action:

• references/simplification-and-polynomials.md — simplify/expand/factor/collect/partfrac/rewrite, sym2poly vs coeffs, variable-precision arithmetic (VPA)
• references/control-systems.md — Deriving transfer functions from ODEs, tf/ss derivation from first principles, Laplace/Fourier/Z-transform, Bode plots from symbolic models
• references/ode-solving.md — dsolve syntax, odeToVectorField + matlabFunction + ode45 pipeline, parameterized ODE solving
• references/plotting-and-display.md — fplot/fsurf/fmesh/fcontour/fimplicit/fanimator family, disp() vs pretty(), why NOT to use linspace+subs+plot
• references/matlabFunction-patterns.md — Converting symbolic expressions to function handles/files, 'Vars'/'Optimize'/'File' options, piecewise handling, critical error-prevention rules

Common Mistakes and Fixes

See also: application-specific mistakes in each reference file.

Checklist Before Generating Symbolic Code

• Using syms (not string-based sym('...')) for variable creation in scripts
• Using == for equations, not =
• Using diff(y, t, n) for derivatives, not D notation
• Specifying the independent variable explicitly in diff, int, laplace
• Assigning subs(...) output to a variable
• NOT wrapping numeric literals in sym() when a symbolic variable is already in the expression
• Setting assumptions with assume/assumeAlso, clearing with syms or assume(x,'clear')

Troubleshooting

Issue: solve returns empty or unexpected results

• Check: Are there assumptions restricting the domain? Use assumptions to check.
• Try: solve(eqn, x, 'ReturnConditions', true) to see conditions on solutions.
• Try: vpasolve for numeric solutions when no closed form exists.

Issue: Stale assumptions causing wrong results

• Fix: Add syms <varname> at the top of your script to clear assumptions.
• Last resort: reset(symengine) clears everything in the session. Suggest it only after the user confirms they accept losing all symbolic state and assumptions; prefer syms x or assume(x,'clear') first.

See also: application-specific troubleshooting in each reference file.