requireSoftware

Stop with a named message when a prerequisite is missing.

Source: src/utilities/requireSoftware.m

Description

requireSoftware errors unless a probe function is reachable on the MATLAB path, and the error names the software the user has to install. It is the guard a demo puts at the top of a script that needs software the MTI-Toolbox itself does not require — a third-party kit, an external model library, or a MathWorks product.

The point is where the failure happens. Without the guard, a missing kit surfaces as an undefined-function error somewhere inside a numerical routine, and the name of the thing to install appears nowhere in the message.

Call it once, early, on the code path that actually needs the software. When the software is present the call returns silently, so a demo whose prerequisites are all met runs untouched.

The probe is resolved with which, so any function, class or block library the software puts on the path is a valid probe. Pick one that is unlikely to be renamed.

Checking a MathWorks product

Pass LicenceFeature to also test the licence. This separates two failures that look alike but need different answers from the user:

What happened	What the message says
The licence is missing — the product was never installed or enabled	Names the product and says to install it. It does not name a MATLAB release, because the product is missing on all of them.
The licence is held, but the release no longer ships the library	Names the release, because that is the cause and there is nothing to install.

A licence test on its own cannot tell these apart: it reports the second case as healthy. On R2026a, license('test','Power_System_Blocks') returns 1 while powerlib is gone, so a licence-only guard passes and the demo then fails inside a library that is not there. Probing the licence and the path is what closes that gap.

Asking instead of stopping

Request an output and nothing is raised: available is false when the software cannot be used, and explanation says why. Demos differ on purpose — some fall back to released results, others cannot continue at all — so the probe is shared while the policy stays with the caller.

Syntax

requireSoftware(softwareName, probeFunction)
requireSoftware(softwareName, probeFunction, sourceUrl)
requireSoftware(___, "LicenceFeature", feature)
[available, explanation] = requireSoftware(___)

Input arguments

Argument	Description
`softwareName`	string. Display name of the required software, as a user would search for it. This is what the message reports.
`probeFunction`	string. Name of one function, class or block library the software provides.
`sourceUrl`	(optional) string. Where to download the software. Omit it for software that cannot simply be fetched, e.g. a licensed MathWorks product.
`LicenceFeature`	(optional name-value) string. The feature name `license()` knows a MathWorks product by, e.g. `"Power_System_Blocks"`. Omit it for third-party software, which has no MathWorks licence to test.

Output arguments

Argument	Description
`available`	(optional) logical. True when the software can be used here. Requesting it suppresses the error.
`explanation`	(optional) string. `""` when available, otherwise a complete sentence naming the cause and what to do about it.

Called with no outputs the function returns silently when the software is present, and raises requireSoftware:MissingSoftware when it is not.

Examples

Guard a demo that multilinearizes a model, which needs the sparse-grid kit:

requireSoftware("Sparse Grids MATLAB Kit", "create_sparse_grid", ...
    "https://github.com/lorenzo-tamellini/sparse-grids-matlab-kit")

Stop a demo that has nothing to fall back on:

requireSoftware("Simulink", "simulink", "LicenceFeature", "SIMULINK")

Degrade instead of stopping, the way the nine-bus demos read released results when they cannot simulate live:

[live, why] = requireSoftware("Specialized Power Systems", "powerlib", ...
    "LicenceFeature", "Power_System_Blocks");
if ~live
    warning("%s", why);
end