Compute: GPU & CPU

Every cufemlab run travels the same reliable path — API to queue to worker to database to artifacts — and each analysis lands on the processor built for it: GPU-first for the heavy motor field solves, CPU for the estimates, utilities, and 3-D field validation.

How a run executes

Whether you submit from the web app at /app/ or from the Python SDK, a run moves through one predictable pipeline:

• 1 · Submit. The FastAPI service authenticates your API key, validates the request against the analysis catalog and its parameter schema, checks credits, and admits the job. Credit checks are fail-closed — see below.
• 2 · Queue. The admitted job is placed on a durable Redis-backed work queue and immediately gets a job id and a QUEUED status you can track.
• 3 · Work. A worker pulls the job and runs the solve on the correct processor — the GPU node for the GPU workflows, CPU otherwise — moving the job through RUNNING to a terminal COMPLETED or FAILED.
• 4 · Persist. Job state, parameters, timing, and outcome are written to Postgres; produced files (field/flux .vtu, waveforms, validation cards, signed PDFs) are stored as artifacts.
• 5 · Return. The API returns the versioned result.v1 envelope with a verdict, a headline value, a summary, and metrics; artifacts are fetched over authenticated download links.

The GPU-first and CPU lanes

The catalog has fifteen live analyses. Nine are GPU-first; six run on CPU. Both lanes produce the identical result.v1 envelope and artifacts — the only difference is which processor does the arithmetic.

Two analysis types are cross-checked against an external reference: cogging_torque_movingband against the open-source FEMM and GetDP solvers, and cufem3d_field_validation against an analytic sphere. Both cite a tolerance and a measured error. cogging_sweep_2d does not carry an oracle card. cogging_torque_movingband is the flagship validated cogging workflow (2-D moving-band / Arkkio) and cogging_sweep_2d is a legacy, superseded 2-D sweep. pmsm_operating_torque and iron_loss_estimate are engineering estimates, not independently validated. See Motor workflow and Physics domains for the details behind each number.

Submitting a run

The SDK mirrors the pipeline above. Create a project, optionally upload CAD, submit an analysis, wait for the terminal state, then read the result. Requesting a GPU workflow is a flag on the submit call; omit max_minutes to use the per-analysis default budget.

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(name="stator-rev-C")
# optional: upload CAD (.step / .stp / .iges / .stl)
# f = client.upload_file(project.id, "rotor.step")

job = client.analyze(
    project_id=project.id,
    analysis_type="cogging_torque_movingband",   # GPU-first workflow
    input_params={"poles": 8, "slots": 12},
    gpu=True,                                  # request the RTX-class node
)                                              # max_minutes omitted -> per-analysis default

job.wait(poll_interval=5)                        # QUEUED -> RUNNING -> COMPLETED
r = job.result()
print(r.verdict, r.value, r.summary, r.metrics)   # result.v1 envelope

For signed_report_generation, call job.download_report("report.pdf") on the completed job to retrieve the deterministic, HMAC-signed PDF (SHA-256 provenance). Full call surface: API reference; more end-to-end scripts: Examples.

The result envelope and artifacts

Every completed job — GPU or CPU lane — returns the same versioned result.v1 envelope, so your client code does not branch on where the work ran:

• .verdict — the outcome (for example a PASS, or a relative-error field verdict for 3-D validation).
• .value — the headline number for the analysis.
• .summary — a short human-readable description of the run.
• .metrics — structured detail: measured quantities, tolerances, and (for validated cogging) the FEMM/GetDP cross-check.

Alongside the envelope, artifacts persist as downloadable files: field and flux data as .vtu, torque waveforms, the per-run validation card, and signed report PDFs. Manage them from /app/reports.html.

Per-user concurrency cap

Each account has a per-user concurrency cap — the number of jobs it may have running at once — which keeps shared GPU capacity fair and queue latency predictable. Submitting a job beyond that cap is rejected cleanly:

Billing is fail-closed

Admission is gated on credits before any compute starts. If the account does not have the credits an analysis requires — or if credit state cannot be confirmed — the job is refused rather than run for free. This is a deliberate fail-closed default.

The 3-D field validation lane

cufem3d_field_validation is cufemlab's live 3-D lane: a 3-D magnetostatic edge-element (Nédélec) solve that produces geometry, mesh, and the magnetic field and flux as .vtu, and returns a relative-error field verdict. It is the geometry-and-field validation lane on the path toward full 3-D motor simulation. It runs on CPU today, is free-trial eligible at 1 credit, and completes in ≤ 5 minutes. Full walkthrough: cufem3d.

3-D field validation is available now; full 3-D motor torque — with skew and end-effects — is on the roadmap. For the complete honest boundary, see Hard limitations and Roadmap.

Start a run →   Read the API reference →