Function reference

All functions live in the opendpd namespace. MATLAB's help opendpd.function also shows each function's short reference. Numeric sample rate and bandwidth arguments use Hz; MATLINK displays MHz.

Environment and MATLINK

studio returns an opendpd.MATLABBridge and retains it for the MATLAB session, so calling without an output keeps MATLINK active. Use disconnect for lifecycle control. Internal request messages and timer state are implementation details, not a stable public automation API. When MATLAB is blocked, requests and the heartbeat wait until callbacks can run again.

link = opendpd.studio("my-pa-workspace", Label="PA capture session");
opendpd.help("gui");
opendpd.disconnect(link);

OpenBrowser=false connects the bridge without launching a browser. Studio pages supported by openStudio are home, matlink, datasets, experiments, new-experiment, results, run and result. The last two require RunID, which is useful in scripts; the MATLINK GUI uses named experiment selection. Only supported local routes are accepted. A returned URL from openStudio is a private bootstrap link; keep it local. Normal use prints no token in the Command Window.

opendpd.openStudio(p, Page="datasets");
opendpd.openStudio(p, Page="result", RunID=job.ID);

Import

ds = opendpd.importIQ(p, x, y, SampleRate=80e6, Bandwidth=20e6, SegmentSamples=2048);
ds = opendpd.importMAT(p, "capture.mat", SampleRate=80e6, Bandwidth=20e6, SegmentSamples=2048);

ds is a dataset struct including dataset_id, sample count and provenance. importIQ accepts dense MATLAB single/double vectors; rows and columns are equivalent. importMAT reads a MAT file of any version in MATLAB and additionally accepts real N×2 I/Q matrices.

Jobs

Training options shared by trainPA and trainDPD:

job.ID and job.Project.Workspace identify a run for reconnection. Complete settings, artifacts and logs remain in the workspace and Studio.

One call: fit

opendpd.fit does what the project API does in order - import the capture, train a PA model, train a DPD through it, export both - in one call, and returns the two models as opendpd.Model objects that run in plain MATLAB.

Python is a separate process. fit starts python -m opendpd.sdk._fit as a child of MATLAB and exchanges files with it; MATLAB's Python integration (pyenv, the py. namespace) is not used or loaded. The Python version therefore need not be one your MATLAB release supports, and a crash in Python cannot take MATLAB down. The interpreter is the first that exists of: PythonExecutable, the OPENDPD_PYTHON environment variable, the one opendpd.studio or opendpd.setup remembered, MATLAB's configured pyenv (reading the setting does not load Python). MATLAB's own library folders are removed from the child's library path (LD_LIBRARY_PATH, DYLD_*, and PATH on Windows) so that system libraries are not replaced by MATLAB's; other entries stay. Ctrl+C asks the running job to cancel and returns once it has stopped (up to a minute, then the process is ended). Verified on R2026a with Python 3.13 on Linux, in a fresh session that left pyenv unloaded; Windows and macOS are not verified.

The workspace service. fit works through the workspace's Studio service. If none is running it starts one and stops it when the call ends. A service that was already running - a Studio you have open on that workspace, or another session's - is used and left running, and so is one that still has other runs; fit only stops what it started. If the service it started does not stop promptly, fit still returns its result and warns (opendpd:fit:ServiceNotStopped).

The exported models are verified against their golden vectors on this MATLAB release before fit returns; if one does not reproduce OpenDPD's outputs, fit fails with opendpd:Verification and names the package. Errors from Python come back with its message: opendpd:FitFailed, opendpd:Cancelled, opendpd:Timeout.

Metrics without a run

These need no project, workspace or server: they call the code that Studio and the run service use, so a number computed here equals the one in a Studio result for the same signal and settings. Metadata that changes a number has no default (SegmentSamples, SampleRate); a metric that cannot be computed is returned with a Status and a Reason, never a guess.

How these compare with MathWorks functions is measured, not assumed: EVM agrees with an independent lteOFDMDemodulate/lteEVM chain to better than 1e-8 percentage points on the registered signals, and the profile's ACLR differs from comm.ACPR by up to 0.2 dB because comm.ACPR integrates the bins that enclose a band edge while OpenDPD sums the bins whose centre lies inside it. The numbers, budgets and the cases that do not agree are in docs/performance/matlab-parity.md of the OpenDPD repository.

Inference and export

See execution semantics before comparing exported and applied waveforms. apply uses stored sample-rate metadata and assumes the supplied samples have the corresponding physical rate; vectors do not carry their own time base.

Model packages: run a trained model without Python

opendpd.export writes a trained PA or DPD as an opendpd-model-v1 package: a zip of data (manifest.json, weights.mat and weights.npz with the same arrays, golden/ with a test input and the outputs OpenDPD produced for it, a README). It holds no code. opendpd.load reads it back as an opendpd.Model that runs in plain MATLAB: no Python, no project, no server, no other toolbox. A run trained in Studio can be exported from a terminal with opendpd export-model RUN_ID --workspace WORKSPACE --out file.opendpd.zip; it writes the same bytes.

opendpd.export(dpd, "apa-dpd.opendpd.zip");           % where the model was trained (Python SDK)
model = opendpd.load("apa-dpd.opendpd.zip");          % anywhere: plain MATLAB
assert(opendpd.verify(model).passed)                  % this release computes the model as OpenDPD did
u = opendpd.apply(model, xTest);                      % the predistorted PA input, like opendpd.apply(dpd, xTest)

mp_ls in an rf.PAmemory (RF Toolbox). The matrix from commCoefficients() is the CoefficientMatrix of rf.PAmemory(Model='Memory polynomial', CoefficientMatrix=C). The only difference from comm.DPD is the initial delay line: rf.PAmemory fills it with the first input sample, not with zeros. To reproduce an OpenDPD segment (zero history) apply it to [zeros(Q-1,1); x] and drop the first Q-1 outputs; the delay line then carries across calls, so a stream can be fed in chunks. Checked on R2026a (RF Toolbox 26.1) against comm.DPD on 36 coefficient/signal cases (largest relative difference 4·10⁻¹⁶) and against opendpd.apply on 3 (4.5·10⁻⁸, the single-precision interface); registered and recorded in docs/performance/matlab-parity-dpd.md (amendment 2). Not checked: the RF Blockset amplifier block, the other nonlinearity models of rf.PAmemory, other releases.

What verify shows and what it does not: a pass means this MATLAB release computes the package's model on the golden input to within 1e-5 of what OpenDPD's apply produced. It does not show that the model is good for your amplifier, and it does not make a package from an unknown source trustworthy: the golden vector comes from the same file. Compare model.SHA256 with the value published by whoever gave you the package.

Reading a package is deliberately narrow. Only the six known file names are accepted (nothing else is extracted, no path from the archive is used), every file must match the SHA-256 in the manifest, entries are copied out with a hard size limit, and the arrays are read from the .npz files by a strict parser that only ever interprets bytes as float32, float64, complex64 or complex128 numbers. The .mat files are for your own code and are never opened by the toolbox: load and whos -file both call loadobj for classes on the MATLAB path, so opening a MAT file from an untrusted source can itself run code. manifest.json is measured before it is parsed, because MATLAB's jsondecode recurses once per level of nesting and ends the MATLAB process with a segmentation fault on a text nested tens of thousands of levels deep, holds several hundred bytes of memory per array element, and needs time quadratic in the digits after the decimal point of one number (a million digits take half a minute): a manifest that nests more than 8 levels, holds more than 20,000 array elements and object members, or has a number of more than 64 characters is refused with opendpd:Package, and the control characters in its text (escape sequences, bells, carriage returns) are replaced by ? before anyone can display it. A manifest that declares fewer GRU layers than the weights hold is refused. The golden test input is synthetic noise with the training input's amplitude statistics, never a slice of your data, so a package can be shared without sharing a measurement.

Execution and numerics: opendpd.apply(model, x) uses the same semantics as for a job (auto, the default, is a stream for gru and gmp and offline_segmented for the others; offline_segmented restarts state every Manifest.signal.nperseg samples and zero pads the last segment; tres_gru reads 16 future samples inside a segment). MATLAB computes in double precision; PyTorch uses float32, so outputs agree to about 1e-7, which is what the golden test measures. Speed on a development machine (R2026a, Linux, no GPU, one MATLAB process) is roughly 0.3 us per sample for mp_ls, 1 us for gmp_ls, 2-5 us for a two-layer gru or tres_gru of hidden size 6-64, and 13 us for a gmp of 495 terms; it is for evaluating waveforms, not a real-time implementation. opendpd.Model loads its weights from a file, so it is not the class to put in a Simulink MATLAB System block or to build with MATLAB Coder: use opendpd.generateCode for that. Not verified: other MATLAB releases or operating systems.

Standalone classes for MATLAB Coder and Simulink

opendpd.generateCode writes a loaded package as a standalone MATLAB class: the weights are constants in the source, the arithmetic is the text of the opendpd.runtime kernels, and nothing is read at run time. The class needs no OpenDPD toolbox, no Python and no file, so it can be used as a Simulink MATLAB System block, built with MATLAB Coder, or given to a colleague who does not have this toolbox.

The files, for Name="ApaDpd": ApaDpd.m, the matlab.System class; ApaDpdStep.m, the entry point for MATLAB Coder; ApaDpdCheck.m, which runs the class on the package's golden test vector and returns passed, max_abs_error and tolerance_abs (at most 1e-5); and README_ApaDpd.md with the provenance (package SHA-256, run, evidence type) and the limits. Every file says in a comment which package it came from.

model = opendpd.load("apa-dpd.opendpd.zip");
r = opendpd.generateCode(model, "apa-dpd-class", Name="ApaDpd", Execution="streaming");
addpath(r.Folder)
ApaDpdCheck()                                      % passed = true: the class computes the model as OpenDPD did
dpd = ApaDpd;  u = dpd(chunk);                     % complex single column; the state is kept between calls, reset(dpd) clears it
codegen ApaDpdStep -args {coder.typeof(complex(single(0)), [Inf 1])}      % MATLAB Coder: a MEX function (or a library)

In Simulink add a MATLAB System block and set its System object name to the class name. The block takes a vector (a frame) or one sample per time step and returns a complex single column; both Interpreted execution and Code generation work. examples/opendpdSimulink.m builds a DPD-then-PA transmit chain this way and compares it with opendpd.apply.

Choose the execution to match how the block is fed. The default of opendpd.generateCode stays offline_segmented (opendpd.apply's auto does not apply to it: a generated class is fed in whatever frames you choose). offline_segmented cuts every call into segments of nperseg samples with a zero state at the start of each, because that is how OpenDPD scored the run: a frame of exactly nperseg samples is one segment, but feeding it one sample per time step makes every sample its own segment with a zero state, which is not the model. For sample-by-sample or frame-by-frame processing of a gru or gmp use Execution="streaming"; tres_gru, mp_ls and gmp_ls have no streaming variant and need whole frames. A class is generated for one execution; generate both if you need both.

What was checked, and on what (MATLAB R2026a, Linux, one machine): for the six small packages in tests/data, each class equals opendpd.apply to within 1e-12 on waveforms of 1 to hundreds of samples and on any chunking (observed: identical), passes its own golden check, builds with MATLAB Coder as a MEX function (variable-size input for every class; fixed-size frames, single samples and double input for the streaming gru), reproduces the golden vector from the MEX function, and runs in a MATLAB System block in both simulation modes on a frame (a DPD then PA chain of streaming gru classes, one sample per time step, equals the MATLAB chain). Not checked: other MATLAB releases and operating systems, C/C++ libraries and embedded targets, GPU Coder, HDL Coder, fixed-point conversion, and packages larger than the fixtures. The arithmetic is double precision on single-rounded inputs, like the MATLAB runtime: this is not a fixed-point or HDL-ready design, and it is not a statement about real-time speed.

Safety. The generated files are code that you will run. The generator puts only numbers it formatted and short, character-restricted provenance text from the package into them, never anything else from the manifest, and refuses a package with a weight that is not finite or with more than 250 000 numbers (use opendpd.apply for those). A package from an unknown source is still a download from an unknown source: compare model.SHA256 with the value you were given before you generate code from it.

Fixed-point deployment packages: check an implementation bit for bit

opendpd deploy RUN_ID --workspace WORKSPACE --out deploy.zip (or the Studio's Deployment panel) writes a fixed-point-v1 package for a one-layer gru run: quantised integer weights, six golden vectors (inputs, outputs and the state after every sample) and a C99 reference that was replayed against them. opendpd.load reads it as an opendpd.FixedModel, which executes the specification's GRU (docs/protocols/fixed-point-v1.md) in plain MATLAB. The integers are held exactly in double precision, so there is no Python, no compiler and no Fixed-Point Designer in the loop. Its purpose is to be a second, independent implementation to check against, and a source of expected values for your own implementation (HLS, RTL, firmware).

model = opendpd.load("deploy.zip");
report = opendpd.verify(model)                      % status "bit_exact": this MATLAB release computes the package's integers
[yq, state, trace] = model.runInteger(xq);          % expected outputs and states for your own implementation
y = opendpd.apply(model, xTest);                    % float in, float out: what the quantised model does to a waveform

What a pass shows and what it does not: this MATLAB release reproduces, bit for bit, every output and state of the six golden vectors that the package carries and that Python computed, and package_c99_status says that the C99 reference did too. It does not show that the specification is right, that the quantised model is good for your amplifier (the package's report lists the quality loss on the test split), or that a hardware implementation is correct. The golden vectors are part of the package, so a package that carries a few trivial ones passes trivially: report.samples_checked says how much was replayed, and runInteger gives you the expected values for stimulus of your own. A package from an unknown source is read like a model package: only the known file names (manifest.json, spec.json, weights.json, README.md, three C sources under c/ and five files for each of the six golden cases the specification names), every file hashed against the manifest, the manifest listing exactly the files that are in the archive and the hashes it gives the golden vectors being the hashes of their files, a hard size limit per entry that depends on what the file is, no path from the archive used, and the C sources checked against their hashes but never compiled or run by the toolbox. The JSON files are measured before they are parsed, because jsondecode ends the MATLAB process with a segmentation fault on a text nested tens of thousands of levels deep, needs several hundred bytes of memory per array element and takes quadratic time on a long number: a file that nests more than 8 levels, holds more array elements and object members than the hidden size and the table limit allow, or has a number of more than 64 characters, is refused with opendpd:Package before it is parsed. The manifest is checked member by member (only the members the format defines, each of the type the format defines, so a logical, a one-character string or an array of character codes cannot stand in for a number or a name) and the control characters in its text (escape sequences, bells, carriage returns) are replaced by ? before anyone can display it. The same measuring and text cleaning protect opendpd.load of a model package.

What the toolbox accepts in a fixed-point-v1 package (the limits are far above what OpenDPD writes: 6 to 24 hidden units, tables of 4096 and 2048 entries, about 72 thousand golden samples):

Every format is taken from the package, never assumed, and the toolbox refuses what it cannot compute exactly: words wider than 16 bits (inputs, state, outputs, weights, table values), a pre-activation wider than 32 bits, an accumulator wider than 53 bits (what double precision holds), weights that are not whole numbers in their word, tables of the wrong length, a rule text that differs from the specification's, and any package for which a sum, product or shift could leave the range below 2^53. It also refuses formats that need a shift of more than 62 places or a value of 2^63 or more: the Python and C99 references hold integers in 64 bits (numpy raises for a right shift of 63 places or more, C leaves it undefined, and a left shift that reaches 2^63 wraps in numpy and is undefined in C), so for such a format there is no reference to agree with. An accumulator that reaches its declared width raises opendpd:FixedOverflow, as the Python reference does.

opendpd.generateCode does not accept a FixedModel (error opendpd:CodegenFixedPoint): the package already carries a generated C99 reference, and a MATLAB fixed-point or HDL design is not provided.

What was checked (MATLAB R2026a, Linux, one machine): two real packages written by opendpd deploy's code path, one with the default specification and one in which every format differs (14-bit input, 14-bit state with 13 fractional bits, 14-bit output with 11, 12-bit weights, a 28-bit pre-activation, a 40-bit accumulator, coarser tables), both with a C99 verdict of bit_exact, reproduce all six golden vectors (5,582 samples per package, outputs and states); a production-size package (24 hidden units, 72,448 golden samples) verifies in 1.3 s (about 18 us per sample); the kernel equals an independent scalar int64 implementation of the specification on 24 random sets of formats and weights; the kernel builds with MATLAB Coder and the MEX function reproduces the golden vectors of both packages. Seeded faults in the arithmetic, the reader and the entry points were each caught by at least one test (see the 2.4.0 release notes for the count). Not checked: other MATLAB releases and operating systems, a fi or HDL Coder implementation (none is provided), packages whose weights come from a run that was trained longer than the fixtures' one epoch, and any hardware.

Measured captures: opendpd.lab

opendpd.lab.Session supervises a measurement made by your instrument code. RF stays off until a named person arms the session, every limit is checked before anything is sent, and every abnormal path - an error in your functions, a timeout, a lost link, a capture that is empty or not finite, Ctrl+C, a failed RF-off - switches RF off and leaves the session tripped, which cannot be armed again. It follows OpenDPD's Python interlock (opendpd/instruments/safety.py, docs/architecture/instruments.md); the instrument adapter is a pair of function handles, so the code your laboratory already has (VISA, a vendor driver, a remote laboratory) is used as it is. No driver ships with the toolbox.

lab = opendpd.lab.Session(MeasureFcn=@myMeasure, RFOffFcn=@myRFOff, Operator="Your Name", ...
    MaxPeak=0.9, MaxOutputPower_dBm=30, PowerCalibration=@myPeakPower_dBm, Timeout=60);
% The next line needs OPENDPD_ALLOW_RF_OUTPUT=1, which you set only in an approved laboratory session.
arm(lab);
y = measure(lab, u, SampleRate=fs);                % limits first, then myMeasure(u, fs); RF off afterwards
disarm(lab);
ds = opendpd.importIQ(p, u, y, SampleRate=fs, Bandwidth=bw, SegmentSamples=2048, Origin="measured", ...
    Source=record(lab, Compact=true));              % the dataset keeps who armed the session and what was played
saveRecord(lab, "session-1.json");                 % the complete record, next to your data

What MATLAB cannot do. It cannot interrupt a running function, so Timeout is checked when MeasureFcn returns, and the heartbeat is checked before and after a measurement, not during it. Give your instrument calls their own time limits (for example the Timeout of a visadev) so that a hung instrument returns by itself. Ctrl+C trips the session through an onCleanup guard that MATLAB documents; that path was not automated in tests (matlab -batch did not react to SIGINT, so the cleanup could not be exercised). If RFOffFcn itself fails the session warns (opendpd:lab:RFOffFailed), is tripped and says that the output may still be on: switch it off at the instrument.

What this is not. A session is a safety wrapper and a record, not a calibration: it does not align delay or gain, does not know your attenuators, and does not establish the amplifier's real output power unless your PowerCalibration does. It has been exercised only on the mock, with injected faults; no instrument chain has been tested with it, so the supervised trial that docs/protocols/measured-dpd.md requires is still to be done on a real bench.

Package resource limits

opendpd.load refuses model packages with a segment or golden-vector length above 1,048,576 samples. opendpd export-model enforces the same limits before producing a package. The default golden has at most 8192 samples. These limits bound package-controlled padding and verification work; user-supplied waveform length is a separate input. NPZ array names contain at most 63 ASCII identifier characters.

When cancelling opendpd.fit, the process transport allows 150 seconds for Python to cancel the run, settle it and stop an SDK-owned service before forcing an exit. An existing Studio service remains owned by its original launcher.