PF Simulation Research library

PF research library · 5 min read

r25 engineering workers

r34 documentation · engineering-integrations.md · Formatted reading copy

On this page
  1. Hosted native FMU
  2. Licensed MATLAB/Simulink worker
  3. Deployment acceptance and evidence

The same engineering backend is used by standalone jobs and the hosted research workflow. Only the packaged Modelica Dahlquist FMU and the two packaged MATLAB clock functions are accepted. Uploading a native FMU, MATLAB function, Simulink model, executable path, or license configuration in a study is not supported.

Hosted native FMU

Build Dockerfile.research and use it as the approved research/FMU worker image. The model remains Dahlquist_v0_0_41.fmu, SHA-256 cecf1fb0f04cbb9de102c783dd7d905a17aec0c6e8ce4641f54a0b26673c2c7f. The adapter verifies this checksum before extraction or native-library loading.

FMPy now extracts the approved model into a unique private temporary directory inside the job output directory and deletes that directory after execution. This avoids FMPy's implicit use of /tmp, which is deliberately mounted noexec by the isolated Docker worker. The hosted /work volume must support loading native shared libraries. An administrator may override the extraction parent with PF_FMU_TEMP_DIR, an absolute existing writable directory on an executable-capable filesystem; the application does not accept this setting from submitted configurations. Do not make a global shared writable execution directory. The default job-local location needs no override.

The actual native model runs twice using CVode relative tolerances 1e-10 and 1e-12. Both trajectories are checked against x(t) = x0 exp(-k t) and each other. The output interval is a sampling request, not CVode's adaptive time step. Both errors and the tolerance-refinement discrepancy are included in the CSV and report. Missing platform binaries or native loading/extraction failure produce an unavailable result, with no passing numerical checks.

This validates FMI interoperability and this specific decay equation. It does not validate a spacecraft, oscillator, instrument, or experimental dataset. The upstream reference license remains in pf_integrations/models/reference_fmus.

The implemented deployment route is MATLAB Engine in a dedicated licensed worker. It is not a MATLAB Runtime or compiled-component deployment. The free MATLAB Runtime cannot execute these Engine calls.

Prepare a private Linux base image with:

  • An installed MATLAB release and the operating-system dependencies required by that release, plus Simulink for the Simulink preset.
  • 64-bit Python 3.12 with venv, pip, and the standard Linux account-management commands. MathWorks lists Python 3.12 support for R2024b, R2025a, R2025b and R2026a; confirm the selected release in the linked compatibility table.
  • A deployment-appropriate license configuration. The PF package neither supplies proprietary products nor determines whether a license covers a particular hosted service.

Build the PF layer from the release directory, substituting the administrator's actual private base image and MATLAB location:

docker build -f Dockerfile.matlab-worker \
  --build-arg MATLAB_BASE_IMAGE=registry.example/pf-matlab-base:approved \
  --build-arg PF_MATLAB_ROOT=/opt/matlab/R2025b \
  --build-arg PF_WORKER_PYTHON=/usr/bin/python3 \
  -t pf-matlab-worker:local .

The recipe installs MATLAB Engine from that installation's extern/engines/python directory into /opt/pf-worker. It deliberately avoids installing an unpinned latest matlabengine package that might target another MATLAB release. The resulting worker uses UID/GID 10001. Its fixed command is:

python -u -m pf_saas.workload --execute /work/execution.json

Set the operator-only matlab entry in PF_SAAS_RESEARCH_PROFILES_FILE to that image, with an explicit profile revision. Configure the permitted license server environment privately in the profile or deployment secret configuration. Do not put license credentials in a Docker build argument or study JSON. See the r25 hosted deployment guide for the complete profile schema and AWS option. The Docker profile must use the service's isolated Docker execution backend.

PF_MATLAB_ROOT is an optional administrator setting. It must name an absolute installation directory with a bin/matlab executable (matlab.exe on Windows). The adapter adds this directory to the worker's executable search path, verifies that matlabroot reported by the actual Engine matches it, then restores the Python process's search path afterward. The matching Engine package remains necessary; changing PATH is not a substitute for installing it.

MATLAB is started headlessly, then the fixed model functions execute in a private writable job directory; only the packaged function directory is added to MATLAB's path. This avoids generating Simulink output in the read-only application tree. The worker uses /work/tmp for temporary files. An operator must confirm the selected licensed base can start under UID 10001 with a read-only root, writable job storage, its required preferences/cache locations, and the permitted license-server network. This image/OS-specific acceptance check requires the licensed installation and has not been executed here.

The adapter reports an unavailable result if Engine import/startup, installation matching, or license checkout fails. Error classification does not copy license server names, credentials, or Engine output into the result. Numerical/model errors still fail the job; they are not converted into successful execution or hidden as missing licenses. The Engine is closed after both success and failure.

Deployment acceptance and evidence

On a licensed worker, execute both shipped presets and retain their reports:

python run_research_integrations.py --config config_r24_matlab_clock.json --output validation_local_matlab_clock
python run_research_integrations.py --config config_r24_matlab_simulink.json --output validation_local_matlab_simulink

Run the same two presets through the hosted workbench. Require actual Engine version metadata, finite clock trajectories, passing analytic comparisons, valid evidence manifests, and matching standalone/hosted values within the reported tolerances before claiming validated MATLAB/Simulink execution. An unavailable result or configured profile alone is not evidence of execution. For the native FMU, run config_r24_fmu_dahlquist.json through both routes and compare the actual decay output and both tolerance-run checks.

test_r25_engineering.py exercises actual native FMPy execution and private extraction. Its MATLAB test doubles cover deployment failures, installation selection, cleanup, and secret suppression only. They are not MATLAB physics validation. Actual MATLAB, Simulink, licensed-image build, and cloud execution remain dependent on the operator's products and infrastructure.

Official references checked 2026-09-20: