matlab

---
name: matlab
description: Build, review, migrate, and safely plan MATLAB or GNU Octave numerical workflows, including arrays, tabular/time data, tests, projects, graphics, MAT files, and explicit Python interoperability.
license: MIT
---

# MATLAB and GNU Octave

Use this skill to design or review numerical code, migrate MATLAB releases,
prepare reproducible projects, and plan trusted execution. MATLAB and GNU
Octave are distinct products: compatibility is partial, not a license or
behavior guarantee.

## Product and license gate

- **MATLAB R2026a is proprietary.** Do not assume MATLAB, MATLAB Online, a
  named toolbox, MATLAB Test, MATLAB Compiler, MATLAB Coder, Parallel Computing
  Toolbox, or an add-on is installed, licensed, or available to the user.
- **MATLAB Runtime is not MATLAB.** It runs compatible applications produced
  with MATLAB Compiler; it cannot run arbitrary source or host MATLAB Engine
  for Python. Building artifacts needs the applicable licensed compiler and
  every product used by the source.
- **GNU Octave 11.3.0 is free software under GPLv3+.** Octave packages are not
  MATLAB toolboxes. Similar names do not imply API, numerical, graphics, or
  licensing equivalence.
- Ask which runtime, release, platform, installed products, and license context
  the user actually has. Treat availability as `unknown` until confirmed.

See [Octave compatibility](references/octave-compatibility.md) and
[execution/product boundaries](references/executing-scripts.md).

## Nonnegotiable safety boundary

Never run an untrusted `.m`, `.mlx`, MEX binary, MAT file, project startup or
shutdown action, package installer, or generated artifact. Static review does
not prove safety.

Treat these as execution or code-loading surfaces:

- `eval`, `evalin`, `assignin`, text-derived `feval`, `str2func`, callbacks,
  timers, app callbacks, and dynamically modified paths;
- `system`, `unix`, `dos`, shell escape `!`, Java, .NET, Python (`py.*`,
  `pyrun`, `pyrunfile`), MEX, and native libraries;
- `mex`, `codegen`, MATLAB Compiler, build tasks, package/project startup, and
  generated code;
- `load`, object deserialization (`loadobj`, custom serialization), function
  handles, Java/System objects, and class code reachable from MAT files.

`.mlx` is an opaque archive for this toolkit and MEX is native executable code.
Do not use Python pickle for exchange. Inspect first, isolate when appropriate,
obtain explicit approval, then invoke a user-confirmed executable and license.
Bundled scripts are static or dry-run tools: none launches MATLAB, Octave,
Python Engine, a compiler, or a subprocess.

## Default workflow

1. **Clarify target.** Record MATLAB release or Octave version, OS/architecture,
   base product versus required toolboxes/packages, expected inputs/outputs,
   numerical tolerances, and whether execution is authorized.
2. **Inventory statically.** Scan `.m` files, opaque artifacts, project paths,
   required products, and MAT headers before any runtime loads them.
3. **Choose code form.** Prefer functions with an `arguments` block for
   automation. Use scripts only for controlled orchestration and live scripts
   for reviewed interactive narratives.
4. **Make semantics explicit.** Record shapes, classes, units, missing-value
   rules, indexing, implicit expansion, RNG algorithm/seed, tolerances, and
   output formats.
5. **Test without hidden state.** Keep fixtures synthetic, paths project-local,
   graphics deterministic, and tests independent of base-workspace residue.
6. **Plan execution.** Generate an argv plan, review startup/path effects and
   licenses, and launch only after explicit approval outside these helpers.
7. **Capture provenance.** Hash named inputs/code and record release, products,
   RNG policy, tolerances, and command plan without dumping the environment.

## Language and data checklist

### Scripts, functions, and live scripts

- Scripts share the caller/base workspace and leave variables behind.
  Functions have local workspaces and explicit inputs/outputs.
- Live scripts (`.mlx`) mix code and rich output but are not plain-text
  review artifacts. Export reviewed code to `.m` for static inspection.
- Avoid `clear all`, broad `addpath(genpath(...))`, dependence on `pwd`, global
  variables, and silent name shadowing. Use project roots and `fullfile`.
- Validate sizes, classes, and values in `arguments` blocks. Remember that
  type declarations can convert inputs; validators check without converting.
- A main function file should match the main function name. Local functions
  are private to the file; since R2024a they can appear anywhere in a script
  outside conditional contexts.

```matlab
function y = scaleSignal(x, options)
arguments
    x (:,1) double {mustBeFinite}
    options.Scale (1,1) double {mustBeFinite, mustBeNonzero} = 1
end
y = x .* options.Scale;
end
```

Read [programming](references/programming.md).

### Arrays, indexing, and numerics

- MATLAB uses 1-based, column-major indexing. `A(i,j)`, `A(k)`, `A(:,j)`,
  `A{...}`, and `A.(name)` have different semantics.
- `*`, `/`, `\`, and `^` are matrix operations; dotted forms are
  element-wise. Use `A\b`, not `inv(A)*b`.
- Since R2016b, compatible dimensions expand implicitly. Assert intended shape
  before operations that could accidentally form an outer result.
- Preallocate when output size is known, but do not vectorize at the cost of
  huge temporaries or unreadable code. Measure with `timeit` or the profiler.
- Compare floating-point results with domain-chosen absolute and relative
  tolerances, not blanket `==` or a magic multiple of `eps`.
- Pin both random algorithm and seed. Use named `RandStream` substreams for
  independent parallel work; do not use time-based `rng("shuffle")` for a
  reproducibility claim.

Read [arrays](references/matrices-arrays.md) and
[mathematics](references/mathematics.md).

### Tables, timetables, and missing values

- A `table` has named, equal-height variables that may have different types.
  `T(rows,vars)` returns a table; `T{rows,vars}` extracts contents; `T.Var`
  selects one variable.
- A `timetable` additionally has row times. Sort, validate time zones and
  uniqueness, then use `retime`/`synchronize` intentionally.
- Missing sentinels are type-specific: `NaN`, `NaT`, `<missing>`,
  `<undefined>`, and empty character vectors. Integer and logical arrays have
  no standard missing sentinel.
- Define import options rather than relying on inference for production data.
  Preserve units, time zones, variable names, encodings, and missing rules.

Read [data import/export](references/data-import-export.md).

## Graphics and export

Use explicit figure/axes handles and `tiledlayout`; label units; set limits,
color scales, font sizes, and colormaps deliberately. Prefer `exportgraphics`
over `saveas` for publication output. In R2026a it exports raster, PDF/EPS/EMF,
SVG, GIF, and interactive HTML; format capabilities differ. Specify
`ContentType="vector"` for suitable PDF/SVG-style output and `Resolution` for
raster output. Review accessibility and embedded-raster behavior.

Read [graphics and export](references/graphics-visualization.md).

## MAT files and exchange

- Version 7 is the normal `save` default; `matfile` creates 7.3 by default.
  Versions 4/6/7/7.3 differ in types, compression, and per-variable limits.
- Version 7.3 is HDF5-based, not an arbitrary HDF5 interchange contract.
  Partial access and chunking can help large arrays.
- Never load an untrusted MAT file. Inventory headers/datasets first. Objects
  can invoke class deserialization behavior; opaque/function/native content
  requires escalation.
- Prefer CSV/JSON/Parquet/HDF5 with a documented schema for simple exchange.
  Do not rename pickle payloads as MAT files and do not deserialize pickle.

Read [data import/export](references/data-import-export.md).

## Projects, analysis, and tests

- Use MATLAB Projects for controlled paths, startup/shutdown tasks,
  dependencies, source control, and reproducible entry points. Review project
  actions before opening an untrusted project.
- `matlab.codetools.requiredFilesAndProducts` and Dependency Analyzer are
  static approximations; dynamic dispatch can cause misses or false positives.
  A required-product report does not prove a license is available.
- Use Code Analyzer (`codeIssues`; legacy text workflows can use `checkcode`)
  and `codeCompatibilityReport` before migration.
- Base MATLAB includes script-, function-, and class-based
  `matlab.unittest` workflows. Parallel runs require Parallel Computing
  Toolbox. Dependency-based selection, richer quality dashboards, generated
  tests, and advanced coverage/equivalence features can require MATLAB Test or
  other products.
- R2026a `runtests` automatically opens and later closes a project when target
  tests belong to a project that is not already open. Account for startup and
  shutdown actions before using this behavior.

Read [programming](references/programming.md) and
[execution/testing](references/executing-scripts.md).

## Python integration, pinned to R2026a

- R2026a supports 64-bit CPython 3.9-3.13 for MATLAB Interface to Python,
  MATLAB Engine for Python, and MATLAB Compiler SDK for Python.
- The current R2026a PyPI package reviewed here is
  `matlabengine==26.1.12` (released 2026-05-08). It requires an installed
  R2026a; MATLAB Runtime alone is insufficient. R2026a also ships a
  preinstalled Engine distribution under one named `matlabroot` path.
- Package installation does not grant MATLAB or toolbox licenses. Configure
  one named interpreter/executable; do not print the full environment,
  `PATH`, `PYTHONPATH`, or credentials.
- `pyenv` controls MATLAB-to-Python interpreter selection. In-process Python
  generally requires restarting MATLAB to switch; out-of-process Python can
  be terminated and reconfigured.
- Starting Engine is an explicit execution action:
  `matlab.engine.start_matlab()` starts a MATLAB process and can check out a
  license. Never call it merely to probe availability.
- Verify conversion semantics for NumPy arrays, pandas DataFrames,
  tables/timetables, strings/missing values, datetime/duration, dictionaries,
  shape/order, and unsupported sparse/object/categorical cases.

Read [Python integration](references/python-integration.md).

## Local helper CLIs

Every helper is network-free, bounded, symlink-rejecting, and nonexecuting.
Run from this skill directory with Python 3.11+. Bash is allowed only to invoke
these Python CLIs and validation commands; never use it to execute a generated
MATLAB/Octave argv plan or untrusted artifact.

| Helper | Purpose |
|---|---|
| `scripts/plan_batch_command.py` | Produce reviewed MATLAB/Octave argv; never execute |
| `scripts/scan_m_code.py` | Scan `.m` text and flag opaque `.mlx`/MEX risks |
| `scripts/validate_project_manifest.py` | Validate paths and declared product/license status |
| `scripts/inventory_mat_file.py` | Header/metadata inventory; never call `loadmat` |
| `scripts/plan_python_compatibility.py` | Check R2026a CPython/Engine compatibility |
| `scripts/reproducibility_report.py` | Hash named local artifacts and emit a bounded report |
| `scripts/generate_function_scaffold.py` | Dry-run or create function and unit-test scaffolds |

```bash
python scripts/scan_m_code.py path/to/source --root path/to/project
python scripts/plan_batch_command.py matlab script path/to/main.m --root path/to/project
python scripts/validate_project_manifest.py project-manifest.json --root path/to/project
python scripts/inventory_mat_file.py data.mat --root path/to/project
python scripts/plan_python_compatibility.py --python-version 3.13
python scripts/reproducibility_report.py --root path/to/project --file src/analyze.m
python scripts/generate_function_scaffold.py analyzeSignal --root path/to/project
```

The scaffold generator defaults to dry-run; writing requires `--write` and
refuses collisions. SciPy and h5py are optional inventory backends; if
authorized, add exact reviewed versions to the caller's project lockfile.
They are not required for `--help` or header-only inventory, and this skill
does not perform package installation.

## References

- [Programming, workspaces, projects, analysis, tests](references/programming.md)
- [Matrices, indexing, types, missingness, performance](references/matrices-arrays.md)
- [Numerical methods, tolerances, RNG, toolbox boundaries](references/mathematics.md)
- [Graphics and `exportgraphics`](references/graphics-visualization.md)
- [Import/export, tables/timetables, MAT semantics and safety](references/data-import-export.md)
- [MATLAB/Octave command-line execution and migration](references/executing-scripts.md)
- [MATLAB and Python interoperability](references/python-integration.md)
- [GNU Octave 11.3.0 compatibility differences](references/octave-compatibility.md)

Bundled JSON assets are the [project manifest](assets/project_manifest_template.json),
[reproducibility manifest](assets/reproducibility_manifest_template.json), and
[R2026a Python table](assets/python_compatibility_r2026a.json). There is no
`templates/` directory and no Markdown file is loaded from `assets/`;
local-link tests enforce this package contract.

## Primary sources (verified 2026-07-23)

- [MATLAB R2026a documentation](https://www.mathworks.com/help/matlab/)
- [MATLAB R2026a release notes](https://www.mathworks.com/help/matlab/release-notes.html)
- [R2026a system requirements](https://www.mathworks.com/support/requirements/matlab-system-requirements.html)
- [Python compatibility by release](https://www.mathworks.com/support/requirements/python-compatibility.html)
- [MATLAB Engine installation](https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html)
- [GNU Octave 11.3.0 release](https://octave.org/)
- [GNU Octave current manual](https://docs.octave.org/latest/)