---
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: MathWorks BSD-3-Clause (see LICENSE)
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):**
```matlab
solve('x^2 + 2*x - 3 = 0')
dsolve('Dy = -a*y')
```
**CORRECT:**
```matlab
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:**
```matlab
% 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:**
```matlab
% 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.
```matlab
% 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:**
```matlab
syms x
f = x^2 + 3*x;
subs(f, x, 2); % Result is discarded!
disp(f) % Still x^2 + 3*x
```
**CORRECT:**
```matlab
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.
```matlab
% 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)
```matlab
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.
## Core Workflow Patterns
### Creating Variables and Expressions
```matlab
% 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
```matlab
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
```matlab
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
```matlab
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
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:
- **`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
| 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)` |
| `clear x` to clear assumptions | `syms x` or `assume(x,'clear')` |
| Using `syms` inside a function | Use `x = sym('x')` inside functions |
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.
- **Nuclear option**: `reset(symengine)` clears everything.
See also: application-specific troubleshooting in each reference file.