radia-optuna

radia-optuna is an independent, separately distributed MATLAB optimization component from the Radia monorepo. It installs the radia.optuna MATLAB namespace, the 21-command optuna_mex, and checked compatibility contracts whose behavioral oracle is Optuna 5.0.0. Its checked public inventory contains 812 present and mapped entries: 749 have evidence derived from an upstream oracle generator and 63 remain explicitly assertion-mapped. The required shared scope is 401/401 evidence-mapped with no asserted required entry. It does not install or load the Radia solver, NGSolve, oneMKL, or Cubit.

Optuna 5.0.0 is also the algorithmic source of truth: native MATLAB and MEX paths preserve its equations, transforms, state updates, boundary handling, defaults, extension points, and seeded random-consumption order. The active implementation uses the 5.0 design directly; removed 4.x APIs and state shims are not kept. MATLAB vectorization, parallel trial scheduling, table/MAT persistence, and Simulink telemetry are performance and workflow extensions around that common algorithm rather than alternative default optimizers.

Install it by itself:

python -m pip install radia-optuna
radia-optuna-path
radia-optuna-doctor --json

Or install the independently versioned release validated by Radia through:

python -m pip install "radia[optuna]"

radia[optuna] installs the native MATLAB/Simulink package without heavy Python numerical dependencies. Use radia[optuna-upstream] when GP, scrambled-QMC, importance, advanced terminators, storage transports, visualization, or lazy integration exports need the pinned upstream Python, SciPy, and PyTorch stack. Individual visualization and integration targets retain the same optional third-party dependencies as upstream Optuna.

Add the printed directory to MATLAB, then use the upstream-shaped API:

addpath("<output of radia-optuna-path>")
study = radia.optuna.create_study( ...
    sampler=radia.optuna.TPESampler(Seed=42));
study.optimize(@(trial) (trial.suggest_float("x", -2, 2) - 0.25)^2, 100);

For a Global Optimization Toolbox-shaped MATLAB workflow, use parameter objects and a persistent session:

p = radia.optuna.OptimizationParameter("Kp", ...
    Value=1, Minimum=0, Maximum=10);
options = radia.optuna.optimoptions("optuna", ...
    Sampler="tpe", Pruner="median", Seed=42, MaxTrials=50);
[x,fval,exitflag,output] = radia.optuna.optimize(@myObjective,p,options);

session = radia.optuna.OptimizationSession(@myObjective,p,options);
session.start(); session.runNext(); session.pause();
session.resume(); session.run();

Generic Simulink optimization is part of the standalone contract. radia.optuna.SimulinkRunner configures Simulink.SimulationInput objects, runs the model, extracts objectives and constraints, classifies failed trials, and records reproducible execution metadata without loading Radia. Radia-owned electromagnetic models and application blocks remain in the main distribution.

The wheel ships two deliberately separated Simulink interfaces. The default radia.simulink.buildOptunaStudyBlock facade exposes only start, cancel, best, status, progress, and best trial. Sampler, seed, pruner, bounds, budget, storage, study review, and trial application live in its mask, so a student can compare configurations, extend a saved study, and apply a result without rewiring the model. The complete six-input/eighteen-output radia.simulink.buildOptunaBlock Level-2 runtime remains available as an advanced interface. radia.simulink.addOptunaMonitor remains available where wired Scope/XY telemetry is genuinely useful.

Both block interfaces require MATLAB/MEX sampling at step time. Their auto route uses TPE for small fixed-numeric budgets where batch routing selects GP. Explicit GP and scrambled QMC (the short-name qmc route) are rejected, including legacy blocks and resumed GP/QMC studies: they call Python per trial. Use those samplers in a batch study instead. The block does not silently substitute unscrambled QMC or the non-oracle MATLAB GP backend. User objective callbacks remain responsible for obeying the same step-time boundary.

radia_optuna_teaching.slx and radia.simulink.buildOptunaTeachingModel provide known-optimum, Pareto, and pruned/failed student exercises. See OPTUNA_SIMULINK_LAB.md. These exercises do not require Global Optimization Toolbox or Simulink Design Optimization.

The distribution is Windows x64 because the current native artifact is optuna_mex.mexw64. Native Random/TPE/evolutionary/pruner workflows do not start Python. Install radia-optuna[upstream] for features intentionally executed through pinned upstream Python packages, including checked GP acquisition, scrambled QMC, and parameter importance.

The native sampler surface includes unified scalar and multi-objective TPE, automatic multivariate selection, concurrent-RUNNING constant liar, named constraints, polynomial mutation, source-trial/separable/margin/learning-rate CMA-ES modes, and deterministic unscrambled Sobol generation through 21,201 dimensions. The Sobol path uses a checked binary conversion of SciPy 1.17.1's Joe--Kuo criterion-6 direction numbers and does not import Python or SciPy at MATLAB runtime.

MAT/table persistence remains a MATLAB extension. An explicit, versioned handoff is available when the same completed history must be opened by an upstream Optuna storage:

radia.optuna.export_study(study, Path="study.json")

radia-optuna-bridge load study.json --storage sqlite:///study.db
radia-optuna-bridge dump returned.json --storage sqlite:///study.db --study-name <name>

radia.optuna.import_study("returned.json") restores trial states, original parameter and attribute names, distributions, intermediate values, constraints, metric names, and study attributes. This is an explicit handoff, not a per-trial Python fallback.

LTspiceRunner, SheetMetalRunner, and internal.runLTspiceTrial are shipped as explicitly classified Radia integration adapters. The standalone core does not call them; choosing one requires the full radia installation.

Upstream attribution

This is an independent, unofficial project. It is not affiliated with, sponsored by, or endorsed by Preferred Networks, Inc. or the Optuna project. It does not use the Optuna logo or present itself as an official Optuna distribution.

Optuna, the Optuna logo and any related marks are trademarks of Preferred Networks, Inc.

Optuna and the official optuna/optuna-mcp server are separate MIT-licensed upstream projects and are not bundled in this wheel. See THIRD_PARTY_NOTICES.md for their copyright and license notices and for the SciPy Sobol direction-data notice. Shared MCP Study/Trial/visualization operations remain owned by the official server; radia-mcp covers only MATLAB/Simulink differences.

Release boundary

CI builds and verifies a distinct radia-optuna-wheel artifact. A radia-optuna-v<version> tag may publish only that exact CI artifact, after rechecking its tag, version, API inventory, MEX inventory, and dependency boundary, including the bundled third-party notice. The verifier byte-matches every staged Python, MATLAB, Simulink, MEX, contract, license, and notice payload against the checked monorepo source; matching version and file counts alone are not sufficient.

radia-mcp.matlab owns the executable MATLAB difference gate. Use matlab_optuna_health, matlab_optuna_oracle_plan, and matlab_optuna_benchmark_plan, then submit the resulting evidence to matlab_optuna_release_gate. Installed-wheel evidence can be captured with:

pwsh -File packages/radia-optuna/tests/run_installed_wheel_simulink.ps1 `
  -Wheel <wheel> -EvidenceOutput C:\temp\radia-optuna-installed.json

MATLAB runs through the MATLAB Engine for Python. The runner installs the matlabengine release matching that MATLAB's version into its isolated venv, checks that the Engine binds to that MATLAB root, and records both in the evidence; the acceptance runs in a function workspace. With -EngineSession <name> the runner reuses that shared session after a PID check and restores its path, folder and environment without quitting it; it refuses a session with loaded diagrams or Radia/Optuna MEX. Without it, the runner starts one dedicated session only when the host has no MATLAB process and no shared Engine, and fails before launch otherwise. release_quad optuna-candidate accepts the same choice per target as --engine-session HOST=NAME.

This evidence includes source-fidelity verification, the installed doctor, standalone Simulink success and typed-failure paths, and all seven persisted tables after MAT reload. Shared Study/Trial MCP operations remain upstream.

Reproducible performance evidence

Long benchmarks live under validation_test/optimization. The Optuna 5 lane uses benchmark_optuna50_python.py and benchmark_matlab_optuna50.m, records the complete machine/runtime/load state, and checks seeded proposal checksums before comparing warmed medians. Results produced against 4.x are historical and cannot satisfy the 0.2.0 release gate. Parallel results remain calibrated scheduler evidence rather than a promise that every CAE objective scales by the same factor; cheap objectives should remain sequential.

Publication also uses the standalone four-machine release-quad lane. After the successful main CI run, execute python tools/release_quad.py optuna-candidate --ci-run-id <id> --target all, then pass the retained wheel to python tools/release_quad.py optuna-done --wheel <path>. Only after that gate passes may the matching commit be tagged. The manual release workflow requires the same CI run ID and the candidate SHA256, publishes that exact wheel to PyPI, and attaches it to the matching GitHub Release.