---

name: matlab-use-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, extracting PDE coefficients (pdeCoefficients), symbolic-to-C code generation (matlabFunction + codegen), symbolic matrix variables (symmatrix), physical units and constants (symunit, newUnit), or rewriting/combining algebraic expressions (rewrite, combine). 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
• Extracting PDE coefficients for use with PDE Toolbox
• Converting symbolic expressions to C code or standalone executables
• Matrix-level (atomic, textbook-style) symbolic linear algebra with symmatrix
• Using physical units or constants in symbolic computations with symunit
• Rewriting or combining algebraic expressions into specific forms

When NOT to Use This Skill

• Purely numeric computation with no symbolic variables (use standard MATLAB numeric functions)
• Statistics, machine learning, or data analysis on numeric datasets
• Image processing, signal processing, or other toolbox-specific workflows that don't involve symbolic math
• String manipulation or file I/O operations
• When the user explicitly asks for numeric approximations only (use double or numeric solvers directly)
• PDE Toolbox mesh generation, boundary conditions, or solving (downstream of coefficient extraction)
• Numeric linear algebra (use standard MATLAB matrix operations)

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 — two correct ways:
syms x                       % Recreate with syms: clears assumptions
assume(x, 'clear')           % Explicitly clear assumptions on x
reset(symengine)             % Nuclear option: clears EVERYTHING

Best Practice: Use syms x to clear assumptions (it resets the variable fresh). Use assume(x, 'clear') when you need to reset a specific variable mid-script. The MATLAB clear command only removes workspace variables — it has no effect on the symbolic engine's assumption store.

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

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 

% Gradient, Hessian, Jacobian, Laplacian, Divergence, Curl — use dedicated functions, not manual diff
syms x y z
f = x^2*y + y^3;
gradient(f, [x, y])              % [2*x*y; x^2 + 3*y^2]
hessian(f, [x, y])               % [2*y, 2*x; 2*x, 6*y]
laplacian(f, [x, y])             % 2*y + 6*y = 8*y (trace of Hessian)
g = [x^2*y; 5*x + sin(y)];
jacobian(g, [x, y])              % [2*x*y, x^2; 5, cos(y)]
V = [x^2*y; y^2*z; z^2*x];
divergence(V, [x, y, z])         % 2*x*y + 2*y*z + 2*z*x
curl(V, [x, y, z])               % [-y^2; -z^2; -x^2]

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
charpoly = det(A - sym('lambda')*eye(2))

% 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:

• 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(), symbolic plotting best practices
• references/matlabFunction-patterns.md — Converting symbolic expressions to function handles/files, 'Vars'/'Optimize'/'File' options, piecewise handling, critical error-prevention rules
• references/extract-pde-coefficients.md — pdeCoefficients workflow for extracting PDE Toolbox coefficients, pdeCoefficientsToDouble, systems of PDEs
• references/symbolic-to-c-code.md — matlabFunction(..., 'File', ...) + codegen pipeline for C/C++ generation, when to use ccode vs full pipeline
• references/symmatrix-workflow.md — Atomic symbolic matrices with symmatrix, symmatrix2sym conversion, symfunmatrix, supported vs unsupported operations
• references/symunit-workflow.md — Physical units/constants via symunit, newUnit/removeUnit, correct constant names (u.hc, u.c_0), unit conversion
• references/rewrite-combine-expressions.md — Valid targets for rewrite and combine, IgnoreAnalyticConstraints for log combination, when to use which function

Common Mistakes and Fixes

| Mistake | Fix | |---------|-----| | solve('x^2=1') | syms x; solve(x^2 == 1, x) | | dsolve('Dy = y') | syms y(t); dsolve(diff(y,t) == y) | | subs(f,x,2) without assigning | f = subs(f,x,2) | | Attempting to clear assumptions with the clear command | syms x or assume(x,'clear') — only these reset the symbolic engine | | Using syms inside a function | Use x = sym('x') inside functions | | Manually extracting PDE coefficients by inspection | Use pdeCoefficients(pdeeq, u) | | Computing Laplacian as sum of second derivatives | Use laplacian(f, vars) | | Using ccode() and manually building C files | Use matlabFunction(..., 'File', ...) then codegen | | Using sym('A', [n n]) for matrix-level algebra | Use symmatrix('A', [n n]) | | Hard-coding physical constants as numbers | Use u = symunit; u.hc; u.c_0; u.m_e | | Using combine(expr, 'power') | Invalid target — valid: 'atan', 'exp', 'gamma', 'int', 'log', 'sincos', 'sinhcosh' | | Computing gradient/Hessian/Jacobian/Laplacian/divergence/curl manually with diff |