Getting started

Open the app, mint an API key, submit your first analysis, and read a structured, evidence-backed result — from the browser or the Python SDK, in a few minutes.

Two ways to run

Both paths hit the same API, the same queue, and the same result.v1 envelope. Point-and-click when you are exploring; script it when you want repeatability.

1. Create an account and an API key

Open /app/ and sign up. Once you are in:

• Create an API key at /app/api_keys.html. The key is shown once — copy it and keep it somewhere safe.
• Store it as an environment variable so the SDK finds it automatically: CUFEMLAB_API_KEY. The client reads this by default; the base URL defaults to https://app.cufemlab.secrotec.nl.

2. First run in the browser

The fastest path to a result, start to finish:

• Create a project. A project groups related jobs and any uploaded geometry. Give it a name from the app dashboard.
• Submit a job from /app/new_analysis.html. Choose an analysis type — start with demo_motor_quick_check for a zero-friction first run — and fill in the parameter form. Each analysis type shows only its own relevant inputs.
• Watch it in the queue at /app/queue.html. The job moves QUEUED → RUNNING → COMPLETED, updating live.
• Read the result. Open the completed job to see the result.v1 envelope — the verdict, headline value, summary, and metrics — plus downloadable artifacts.
• Optionally sign it. Generate a deterministic, HMAC-signed PDF evidence report from any completed job via /app/reports.html.

3. The same run from the SDK

The minimal end-to-end flow: create a project, run the demo workflow, wait for it, and read the structured 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(name="Quick check")

job = client.analyze(
    project_id=project.id,
    analysis_type="demo_motor_quick_check",
)                                             # omit max_minutes → per-analysis default

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

result = job.result()
print(result.verdict, result.value)            # verdict + headline value
print(result.summary)                          # human-readable summary
print(result.metrics)                          # structured numbers

To run against your own geometry, upload it first and pass the returned file IDs into analyze(...):

• client.upload_file(project.id, path) accepts .step, .stp, .iges, and .stl geometry.
• Pass typed input_params and, where a workflow uses a file, input_file_ids. GPU-eligible analyses accept a gpu flag.
• Leave max_minutes out to use the per-analysis default — do not set it above the per-type limit.

4. Read the result and artifacts

Every completed job returns the same result.v1 envelope, whether you fetched it from the browser or the SDK:

• result.verdict — the outcome, such as PASS or PARTIAL (for validated workflows, measured against a declared tolerance).
• result.value — the single headline number for the run.
• result.summary — a short human-readable description of what was computed.
• result.metrics — the structured, machine-readable numbers behind the headline.

Alongside the envelope, each job produces artifacts — plots, field files (VTU for the 3-D lane), and, for the validated cogging workflow, an independent FEMM / GetDP validation card that cites the tolerance and the measured error. The API keys, the result.v1 envelope, and artifact download all work end to end.

5. Generate a signed evidence report

When you want something auditable, run the signed_report_generation utility against a completed job. It produces a deterministic, HMAC-signed PDF with SHA-256 provenance over inputs, code, and materials — so anyone can confirm the report matches the run it claims to describe.

report = client.analyze(
    project_id=project.id,
    analysis_type="signed_report_generation",
    input_params={"source_job_id": job.id},        # the completed job to sign
)
report.wait()
report.download_report("report.pdf")             # HMAC-signed PDF, SHA-256 provenance

The same report is one click away in the browser at /app/reports.html.

The catalog: 15 workflows, all live

The catalog holds fifteen analysis workflows: eight magnetics workflows (below), a thermal / core-loss / coupling lane and a neural surrogate — documented in Thermal, core-loss & FNO — plus GPU-accelerated 3-D field analysis (cufem3d_gpu_field_analysis), which runs on compatible GPU workers and reports the actual execution backend and fallback state in its runtime metadata. See the feature matrix for all fifteen. The eight magnetics workflows, including the 3-D field validation lane:

• demo_motor_quick_check — the zero-friction first run (CPU).
• cogging_torque_movingband — the flagship, validated 2-D cogging workflow (moving-band / Arkkio), independently cross-checked against FEMM and GetDP with a per-run validation card (GPU-first).
• pmsm_operating_torque — 2-D operating-torque engineering estimate (GPU-first).
• iron_loss_estimate — Steinmetz-type core-loss engineering estimate (CPU).
• material_comparison — compare electrical-steel and magnet grades from the materials catalog (CPU).
• signed_report_generation — deterministic HMAC-signed PDF evidence from a completed job (CPU).
• cufem3d_field_validation — the 3-D lane: a magnetostatic edge-element (Nédélec) solve returning geometry, mesh, magnetic field & flux (VTU) and a relative-error field verdict (CPU; free-trial eligible, 1 credit, ≤5 min).
• cogging_sweep_2d — legacy 2-D sweep, superseded by the moving-band workflow; prefer cogging_torque_movingband.

For the full parameter reference of each workflow, see the cufem engine API and examples & recipes; the validated motor path is documented in the motor workflow.

What is validated, what is maturing, what is roadmap

We keep current capability and roadmap clearly separated so you always know how much weight a number carries.

3-D field validation is available now; full 3-D motor simulation with torque, skew, and end-effects is on the roadmap. See physics domains and the roadmap for where this is heading, and hard limitations for the honest scope statement.

Credits and billing

Billing is fail-closed: Stripe is not activated, so nothing charges a card. Free-trial credits cover the free-eligible analysis types — including the 3-D field validation lane (1 credit, ≤5 min) — so you can complete the first-run path end to end at no cost. You can review your balance and usage at /app/credits.html.

Next steps

• Motor workflow — the validated 2-D cogging path in depth.
• Examples & recipes — ready-to-run job specs for each workflow.
• cufem engine API — the full SDK and REST surface.
• Physics domains — where the 3-D field validation lane fits.
• Hard limitations — read before relying on a result in production work.

Questions about scoping a run or a result you did not expect? Reach us at contact or request a pilot. cufemlab is built by Secrotec B.V.