Reference

Public API reference

cufemlab v0.3.0-platform-mvp public surface. Anything not listed here is internal and may change without notice.

Rule of thumb. If a public method isn't implemented yet, it raises NotYetImplemented with a pointer to the roadmap. It will never return a silent zero or a calibrated placeholder.

⚠ This page documents the server‑side engine API (illustrative). The cf.* symbols below describe what the engine exposes inside the GPU server; the engine is not installed locally, so import cufemlab raises ModuleNotFoundError in a notebook. To call the platform from your Jupyter session or your own code, use the installed cufemlab_client SDK (HTTPS API client) — see the runnable Motor‑workflow example.

cufemlab top level

import cufemlab as cf

cf.__version__              # "0.3.0-platform-mvp"
cf.materials.list()         # list of cited material entries
cf.materials.load(name)     # load a material by ID
cf.workflows.IntegratedMotorWorkflow(materials=...)
cf.solvers.Magnetostatic2D(mesh, materials)
cf.solvers.TransientThermal(mesh, materials, dt, steps)
cf.solvers.LinearElasticity(mesh, materials)
cf.solvers.StokesLidCavity(mesh, materials)
cf.reporting.Report(result, output_dir)

cufemlab.materials

Function	Returns	Notes
`list()`	`list[str]`	All 53 cited material IDs.
`load(name)`	`Material`	Loads YAML 1.1 file from `materials/`.
`list_with_metadata()`	`list[dict]`	Each entry carries citation + provenance.

Material schema

# materials/m19_steel.yaml
name        : M19 silicon steel
citation    : ASTM A677 / Wang 2018 IEEE TIA
density     : 7650         # kg/m^3
mu_r        : 4000         # relative permeability (linear region)
bh_curve    : [[0.0, 0.0], [0.5, 100.0], ...]  # B-T data points
thermal:
  k         : 28.0         # W/m-K
  cp        : 460.0        # J/kg-K
mechanical:
  E         : 210e9        # Pa
  nu        : 0.30
  yield     : 350e6        # Pa

cufemlab.workflows

IntegratedMotorWorkflow

w = cf.workflows.IntegratedMotorWorkflow(materials="materials/m19_steel.yaml")

result = w.run(
    stator_od      = 0.20,    # outer diameter, m
    current_a      = 12.0,    # phase current, A
    slot_temp_k    = 393,     # ambient slot temperature, K
    cooling        = "natural",
    safety_factor_target = 5.0,
)

# Result fields
result.verdict          # "PASS" | "PARTIAL" | "MODEL_MISMATCH" | "FAIL"
result.B                # peak airgap flux density, T
result.T_max            # peak winding temperature, K
result.safety_factor    # rotor mechanical safety factor
result.provenance       # SHA-256 of inputs + code + materials
result.checks           # list of (sub_verdict, ref, tol, err)
result.cuda_event_ms    # > 0 if any GPU kernel ran

cufemlab.solvers

Magnetostatic2D

s = cf.solvers.Magnetostatic2D(mesh, materials)
A  = s.solve(boundary_conditions=bc, current_density=J)
Bx = s.flux_density()      # cell-centred B vector
verdict = s.benchmark(reference="wang_2018")
# verdict.error, verdict.tolerance, verdict.passed

TransientThermal

s = cf.solvers.TransientThermal(mesh, materials, dt=0.01, steps=1000)
T = s.solve(T0=293.0, source=Q, boundary=bc)
verdict = s.benchmark(reference="carslaw_section_2_3")

LinearElasticity

s = cf.solvers.LinearElasticity(mesh, materials)
u, sigma = s.solve(load=f, boundary=bc, use_gpu=True)
verdict = s.benchmark(reference="timoshenko_section_73")

StokesLidCavity

s = cf.solvers.StokesLidCavity(mesh, materials)
psi, omega = s.solve(lid_velocity=1.0)
verdict = s.benchmark(reference="burggraf_1966")

cufemlab.reporting

r = cf.reporting.Report(result, output_dir="reports/")
r.write_pdf()           # signed PDF with all verdicts + provenance
r.write_json()          # machine-readable verdict record
r.write_markdown()      # for inclusion in pull requests / reviews

Verdict taxonomy

Verdict	Meaning
PASS	Cited benchmark within declared tolerance, error measured.
GPU_PASS	PASS plus a measured CUDA event > 0.
PARTIAL	Some checks within tolerance, others outside — reported, not hidden.
FAIL	Measured error exceeds tolerance; the runner exits non-zero.
NOT_IMPLEMENTED	Method explicitly raises with a roadmap pointer.

Errors you may encounter

Exception	What it means
`NotYetImplemented`	This API exists by name but the physics path is deferred to a later release.
`BenchmarkMissing`	A benchmark suite was invoked without a cited reference loaded.
`ToleranceUndeclared`	Cannot evaluate a verdict without a declared tolerance band.
`ProvenanceError`	Material file or input changed mid-run; recompute the hash.

What's not in the public API

The CLI helpers, the integration runner, and the internal solvers under cufemlab._internal are subject to change. Do not import from underscore-prefixed modules in production code.