cufem engine API

The public HTTPS API and Python client SDK for running cufemlab analyses — submit a job, read a structured verdict, and pull a signed evidence report, all against one canonical base URL.

What this page covers

cufemlab exposes two equivalent front doors onto the same solver fleet:

• The self‑serve web app at /app/ — submit from /app/new_analysis.html, watch progress in the queue, and collect artifacts under reports.
• The Python client SDK (cufemlab_client) — the programmatic surface documented here, built for scripting and CI.

This is the product API. Internal solver symbols are not part of the contract and are not documented here.

Authentication & keys

Create and rotate keys in the app at /app/api_keys.html, then hand the key to the client. Keep it in an environment variable — never in source control.

Quickstart

The SDK is a small, flat client: construct Client, create a project, optionally upload geometry, call analyze(…), wait, and read the result.

import os
from cufemlab_client import Client

client = Client(api_key=os.environ["CUFEMLAB_API_KEY"])   # base url defaults to https://app.cufemlab.secrotec.nl

project = client.create_project("PMSM cogging pilot")

# Validated moving-band cogging workflow (GPU-first).
# max_minutes omitted -> the per-analysis default limit is used.
job = client.analyze(
    project_id=project.id,
    analysis_type="cogging_torque_movingband",
    input_params={"poles": 8, "slots": 12, "current_a": 0.0},
    gpu=True,
)

job.wait(poll_interval=10)          # blocks until the job leaves the queue
result = job.result()

print(result.verdict)                # "PASS" | "PARTIAL" | "FAIL"
print(result.value)                  # headline number for this analysis
print(result.summary)                # summary object: title, description, units
print(result.metrics)                # dict: tolerance, measured error, cross-check ...

The client surface

These are the only calls you need. Anything with a leading underscore is internal and unsupported.

• Client(api_key) — the entry point. Base URL defaults to https://app.cufemlab.secrotec.nl.
• create_project(name) → a project object carrying project.id. Projects group related runs and their artifacts.
• upload_file(project_id, path) → an uploaded‑file object carrying an id. Accepts .step, .stp, .iges, and .stl geometry.
• analyze(project_id=…, analysis_type=…, input_params=…, [input_file_ids], [gpu], [max_minutes]) → a job. Arguments are keyword‑only; input_file_ids attaches uploaded geometry and gpu requests the GPU lane where the analysis supports it.
• job.wait(poll_interval) — blocks, polling the queue until the job reaches a terminal state.
• job.result() → a result.v1 envelope with .verdict, .value, .summary, and .metrics.
• job.download_report(path) — saves a signed PDF for report‑producing analyses (see signed reports).

Analysis catalog

The catalog is fifteen live workflows. Pass the exact analysis_type ID string. Two of them anchor the catalog:

All 15 analysis_type IDs

• demo_motor_quick_check — fast sanity run to exercise the pipeline end‑to‑end. CPU.
• cogging_torque_movingband — validated 2‑D moving‑band / Arkkio cogging; independent FEMM/GetDP card each run. GPU‑first.
• cogging_sweep_2d — legacy 2‑D angle sweep, superseded and partial; prefer cogging_torque_movingband. GPU‑first.
• pmsm_operating_torque — 2‑D operating‑torque engineering estimate (not independently validated). GPU‑first.
• iron_loss_estimate — Steinmetz‑type core‑loss engineering estimate. CPU.
• material_comparison — utility: compare electrical‑steel and magnet grades from the materials catalog. CPU.
• signed_report_generation — utility: deterministic HMAC‑signed PDF evidence report with SHA‑256 provenance from a completed job. CPU.
• cufem3d_field_validation — 3‑D field & flux validation utility; relative‑error field verdict. CPU.
• cufem3d_gpu_field_analysis — experimental GPU‑accelerated 3‑D field analysis, available on compatible GPU workers. Parametric (no upload): mesh_n (12–32), box_L (2.0–4.0), allow_cpu_fallback (bool, default false), run_reference_check (bool, default false). Runtime metadata reports the actual execution backend and fallback state. Fail‑closed: with no GPU the job fails rather than silently running on CPU. Not an independently validated 3‑D torque prediction. GPU.
• thermal_conduction_steady — GPU steady heat conduction (−div(k grad T)=Q, P1 tets); internally validated (MMS, energy balance), external passport not yet attached. GPU.
• thermal_conduction_transient — GPU transient heat conduction (θ‑method, Crank‑Nicolson order 2); internally validated. GPU.
• eddy_thermal_coupled — eddy skin‑effect Joule loss driving a thermal response (energy chain); internally validated. GPU.
• core_loss_estimate — Bertotti 3‑term core‑loss separation with cited coefficients; internally validated. CPU.
• coreloss_thermal_coupled — core‑loss density driving a cooled‑block thermal response; internally validated. GPU.
• field_to_field_neural_operator — experimental in‑distribution neural surrogate / self‑validating demo (held‑out rel‑L2 0.68% on the training distribution; OOD degrades); not general‑purpose, custom‑field input is a follow‑on. GPU.

Uploading geometry (3-D field validation)

Geometry‑driven analyses take one or more uploaded CAD/mesh files. Upload first, then pass the file ids into analyze(…).

project = client.create_project("rotor 3-D field check")

# Accepted geometry: .step / .stp / .iges / .stl
geometry = client.upload_file(project.id, "rotor.step")

job = client.analyze(
    project_id=project.id,
    analysis_type="cufem3d_field_validation",
    input_params={"field_tolerance": 0.05},
    input_file_ids=[geometry.id],
)

job.wait(poll_interval=10)
result = job.result()

print(result.verdict)                        # relative-error field verdict
print(result.metrics["relative_error"])   # measured field error vs tolerance

The result envelope

job.result() returns a stable result.v1 object. Read these four fields:

• result.verdict — the categorical outcome, e.g. "PASS", "PARTIAL", or "FAIL".
• result.value — the single headline number for the analysis (for example the cogging peak, or the 3‑D relative field error).
• result.summary — a structured summary object carrying a title, a human‑readable description, the primary value, and its units.
• result.metrics — a dict of supporting numbers: declared tolerance, measured error, and — for the validated cogging workflow — the FEMM/GetDP cross‑check figures.

Artifacts (VTU fields, waveforms, validation cards, signed PDFs) are attached to the job and also visible under /app/reports.html.

Every result carries schema_version: "result.v1", a validation_card (for the new thermal / core-loss types this is not_validated — internally validated, no external passport yet; the neural surrogate is not_validated and experimental), and a list of downloadable artifacts, each fetchable at GET /api/v1/jobs/{job_id}/artifacts/{artifact_id}.

Validation & error responses. Invalid domain parameters return HTTP 422; a job with insufficient balance returns 402 INSUFFICIENT_CREDITS; a second concurrent job over the per‑user cap returns 429 CONCURRENCY_LIMIT_EXCEEDED (max 2 concurrent). All calls require authentication (Bearer access token or X‑API‑Key).

Signed evidence reports

signed_report_generation turns a completed job into a deterministic, HMAC‑signed PDF with SHA‑256 provenance — the same bytes every time for the same inputs. Run your analysis, then generate the report and download it.

# 1) run any analysis to completion
run = client.analyze(
    project_id=project.id,
    analysis_type="pmsm_operating_torque",
    input_params={"poles": 8, "slots": 12, "current_a": 18.0},
    gpu=True,
)
run.wait(poll_interval=10)

# 2) produce a deterministic HMAC-signed PDF with SHA-256 provenance
report = client.analyze(
    project_id=project.id,
    analysis_type="signed_report_generation",
    input_params={"source_job_id": run.id},
)
report.wait(poll_interval=5)
report.download_report("report.pdf")   # signed PDF + provenance

Errors & limits

The SDK surfaces failures as typed exceptions and HTTP status codes so your scripts can branch on them:

• AuthenticationError — the API key is missing or invalid.
• ValidationError — an unknown analysis_type, malformed input_params, or a max_minutes above the per‑type limit.
• HTTP 402 — out of credits. Billing is fail‑closed; top up at /app/credits.html.
• HTTP 429 CONCURRENCY_LIMIT_EXCEEDED — you exceeded your per‑user concurrency cap. Let a running job finish, then resubmit.

What the API does — and does not — claim

The 3‑D field validation lane is live now and is a real Nédélec magnetostatic solve of the magnetic field and flux; full 3‑D motor simulation with torque, skew, and end‑effects is on the roadmap.

Next steps

• New to the platform? Start with Getting started, then the motor workflow.
• Copy‑paste recipes live in Examples & recipes.
• The 3‑D lane is covered in depth on cufem3d; compute placement in Compute: GPU & CPU.
• Read the hard limitations before you quote a result to a customer.
• Need access? Request a pilot or book a technical evaluation.