One design contract.
Your choice of solver.

Quickstart

1. Start MetaClaw and open its Dashboard. Complete runtime pairing and configure a supported execution route.
2. Download example-evaluation.yaml. It contains a complete, unsolved free-space PEC antenna with a finite port and three frequency samples.
3. Set the runtime address. If runtime authentication is enabled, set your control token in METACLAW_CONTROL_TOKEN. Submit the file using the headers below.

PowerShell · Use the address displayed by your runtime if its port differs.

$runtime = 'http://127.0.0.1:8505'
$headers = @{
  Accept = 'application/yaml'
  'x-antenna-client-version' = '2'
}
if ($env:METACLAW_CONTROL_TOKEN) {
  $headers['X-MetaClaw-Control-Token'] = $env:METACLAW_CONTROL_TOKEN
}
$request = @{
  Uri = "$runtime/api/antenna/live/workspace/evaluations"
  Method = 'Post'
  Headers = $headers
  ContentType = 'application/yaml'
  InFile = './example-evaluation.yaml'
}
Invoke-WebRequest @request | Select-Object -ExpandProperty Content

The response is a job record. Use its id to read progress and the final result:

$jobId = '<id returned by the runtime>'
$status = Invoke-WebRequest "$runtime/api/antenna/live/workspace/jobs/$jobId" -Headers $headers
$status.Content

The example demonstrates the request contract. Its coarse mesh and short temporal window do not establish a converged antenna result.

Runtime setup

The default base URL is http://127.0.0.1:8505/api/antenna/live/workspace. MetaClaw can choose another local port when that port is occupied. Read the running instance’s address and check GET /api/hello for its runtime and connection state.

The runtime administrator configures Python, solver device, precision, thread budget, cache location and PNGF banks. These are deployment settings; an evaluation request supplies physical inputs and bounded execution controls.

Local solver routes are configured in .metaclaw/runtime/antenna-evaluation.yaml, or the administrator’s METACLAW_ANTENNA_CONFIG path. The configuration uses schema metaclaw.antenna-runtime/1. Restart the runtime after changing deployment configuration.

schema: metaclaw.antenna-runtime/1
solvers:
  harp_v1:
    python_executable: 'C:/absolute/path/to/python.exe'
    device: cpu
    mode: direct
    precision: float32
    threads: 8
    cache_root: 'D:/absolute/path/to/antenna-cache/harp'

Download this runtime configuration template. Replace its paths with an interpreter that contains the MetaClaw solver packages and their native dependencies. CUDA routes additionally need a supported NVIDIA GPU, driver and runtime.

Add a witwin_maxwell route with device: cuda:0, mode: direct and precision: float32. A pngf route also needs compatible complete banks in bank_directories, or the administrator-configured metaclaw_solvers.pngf_reference.antenna_bank:build builder with its explicit native or WSL toolchain configuration. A missing bank is an admission blocker unless a builder is configured.

Use /catalog to discover integrations and /readiness to inspect the current route. Readiness and native preparation provide separate checks; a listed solver may still have missing dependencies or reject the scene.

Authentication & transport

The hosted browser pairs with the runtime and sends a runtime-issued X-MetaClaw-Control-Token. Direct local clients may use the default unauthenticated loopback policy; authentication is required when enabled by the administrator. Pair through the Dashboard. A manual client may exchange the code shown by the runtime’s own page with POST /api/configurator/pair and a YAML body containing code. The response includes a token and its expiry.

Keep the token in your local environment or client session. The hosted browser uses its paired transport. Browser origins must be allowed by the runtime; automatic pairing is available only when the runtime explicitly permits it.

Send one bounded YAML mapping per request. Workspace paths accept no query parameters. The workspace API uses the runtime’s loopback interface; remote solver resources are configured behind that runtime.

Geometry & selections

metaclaw.antenna-scene/1 describes geometry in metres. Model setup is organized into geometry, Materials, Excitations, Boundary conditions, Mesh and Analysis. These familiar HFSS categories map to the existing API fields below.

Support statements in these sections apply to the shared HARP, WiTwin Maxwell and PNGF antenna evaluator. Each configured route still checks physical eligibility and available resources through /readiness.

A candidate chooses from the scene’s design conductors. It cannot remove fixed terminals or short the declared source gap.

candidate:
  id: candidate-002
  conductor_ids: [left, right]
solver: harp_v1
settings:
  harp_mode: hybrid
  seconds: 600
  duration_ns: 2

This fragment accompanies a complete scene. Curved conductors and arbitrary CAD are outside this scene grammar. For a complete request, use the downloadable example.

Materials

Define properties in scene.materials, then assign each material to a rectangular volume in scene.dielectrics using material_id. Dielectric volumes must have positive extent and must not overlap internally.

Material and volume assignment

This is a scene fragment for a lossless substrate. Its bounds must fit the complete scene’s mesh and remain inside the PML interior.

materials:
  - id: substrate
    epsilon_r: 2.56
    mu_r: 1
    loss:
      kind: conductivity
      sigma_s_m: 0
dielectrics:
  - id: pcb
    material_id: substrate
    bounds_m: [-0.005, 0.005, -0.005, 0.005, 0, 0.0002]

Terminology reference: HFSS Materials Technical Notes ↗. The values above are example inputs, not measured material data.

Excitations

scene.ports defines the electrical feed. The shared contract supports exactly one finite Lumped Port between two fixed conductor terminals.

Lumped Port definition

The following port is taken from the complete downloadable example; it depends on that example’s terminal geometry.

ports:
  - id: drive
    type: lumped
    reference_ohm: 50
    positive_conductor_ids: [positive]
    negative_conductor_ids: [negative]
    sheet_bounds_m: [-0.001, 0.001, -0.001, 0, 0, 0]
    integration_line_m:
      - [-0.001, -0.0005, 0]
      - [0.001, -0.0005, 0]
    deembed_m: 0

Source waveform

Time-domain HARP and WiTwin use a Gaussian pulse. The shared evaluator derives its center frequency from the midpoint of the requested band and its width parameter from the larger of the band span or 20% of that center frequency. PNGF solves the frequency-domain port response at the requested samples.

Declare exactly one optional source object to set amplitude and phase. Without it, the legacy matched 1 V drive is used. The port fixes source resistance and current contour. A current source means Norton current with that 50 Ω parallel resistance; it does not mean an ideal unshunted current source.

HARP and WiTwin apply phase to the carrier of a time-domain Gaussian pulse. PNGF applies a frequency-domain phasor at every requested frequency. Compare S11 and Zin across routes; the raw voltage and current spectra have different source-waveform conventions.

excitations:
  - id: source-1
    kind: lumped_current
    port_id: drive
    amplitude_a: 0.02
    phase_rad: 0.25
# Or kind: lumped_voltage with amplitude_v instead of amplitude_a.

Terminology reference: HFSS Excitations ↗.

Boundary conditions

Conductor boundaries and exterior truncation have separate roles. Conductor geometry sets the metal surfaces; scene.boundary and scene.mesh.pml_cells define the open simulation domain.

boundary:
  type: open
  padding_m: 0.004
# In the complete scene.mesh mapping:
# pml_cells: 2
 # axes_m: {x: [...], y: [...], z: [...]}
# Or specify all six faces explicitly:
# boundary:
#   type: faces
#   padding_m: 0.004
#   faces: {x_low: pml, x_high: pec, y_low: pml, y_high: pml, z_low: pml, z_high: pml}

padding_m sets the HFSS open-region size. It is informational for the Yee and PNGF routes: explicit mesh axes determine those domains and the field does not generate mesh nodes or enforce this padding value. Keep geometry and the port inside the non-PML region, and verify exterior clearance and PML sensitivity for the antenna.

mesh.pml_cells sets layer thickness only on faces assigned PML. Non-PML faces end at the explicit mesh extent. Geometry and the port retain at least one grid-node margin from each outer face. The open shorthand means six PML faces. HARP, WiTwin and PNGF reject unsupported faces; the separately managed HFSS route currently accepts only the open shorthand and no independent source object or diagonal material.

Terminology reference: Assigning Boundaries in HFSS ↗.

Mesh

scene.mesh.axes_m contains explicit, strictly increasing x, y and z node arrays in metres. These define the Cartesian grid. scene.mesh.pml_cells specifies the PML layer count; see Boundary conditions.

Place conductor surfaces, dielectric interfaces and the finite port deliberately on this grid. WiTwin additionally requires outer PML cells to continue the spacing of the adjacent interior cells. Geometry and resource admission can reject an incompatible grid.

The shared HTTP request does not expose HFSS adaptive tetrahedral meshing or automatic convergence passes. Submit separately refined scenes to study spatial convergence. HARP’s adaptive mode selects an execution method; it does not refine this mesh.

Analysis & frequency sweep

There is no interpolating or fast-sweep selector in this contract. HARP and WiTwin extract the requested samples from time-domain propagation; PNGF solves at those frequencies. Far-field patterns and multiport S-parameter matrices are outside the current shared output contract.

Check mesh refinement, temporal window, time step and exterior truncation before treating the result as physically converged. Inspect the actual mode, work counts and evidence in Results & evidence.

Endpoints

All paths below are relative to /api/antenna/live/workspace. Responses use YAML. Download the OpenAPI specification for request schemas and status definitions.

Job lifecycle

After a runtime restart, unfinished retained jobs become interrupted. Submit a new bounded job when ready. A cancelled or failed job may retain earlier completed candidate records; inspect each record’s identity and evidence.

ADO request controls

Send algorithm: ado, a reproducible seed, max_evaluations, max_seconds, and an optional configured model and goal. The initial design and subsequent accepted proposals use the same solver adapter. Model proposals and native evaluations are recorded separately.

Solver support

HARP mode is requested through settings.harp_mode. The result records the actual selected mode and qualification outcome. Adaptive execution may choose direct; a requested hybrid or reduced route does not guarantee a faster accepted solve.

Prepared finite-window families

Prepared design families use a separate compact query: metaclaw.harp-finite-window-query/1. It contains family_id, width_mm, frequencies_hz, accuracy_policy: validated_points and expected_evaluations. The deployment owns the model and qualification bundle. Requests cannot supply filesystem paths or replace the prepared source, boundary, materials or time window.

For this route, request direct, hybrid, reduced or adaptive. Reduced has local-response and whole-device implementations; the existing scene API retains hybrid_response for local reduction. Adaptive measures eligible implementations for the exact width and declared repetition count, records rejected trials and preparation costs, and reuses only a compatible decision. A changed width may require new planning.

The result separates the requested logical mode, implementation_mode, actual device, planning cost and fresh solve counter. A saved output is not a fresh evaluation. Whole-device qualification covers listed measured widths only; it does not certify arbitrary edits or continuum convergence. The older whole_device_rom query remains a separate harmonic-response contract.

Device and precision are administrator-selected. Use the runtime catalog for other configured integrations, including separately managed external solvers. Solver-specific limitations and licenses still apply.

Preparation & reuse

Preparation files may survive a job. Resident resources are owned by the active evaluation session and released at its lifecycle boundary; a later HTTP job should not assume resident reuse. The result’s reuse record describes what actually happened.

PNGF’s builder constructs the complete bank required by the declared scene, including mutual interactions and output mappings. Bank generation and qualification costs remain visible. Its current bank identity also includes the scene name, targets and provenance, so cosmetic changes may trigger a rebuild. Identical-antenna throughput does not establish the cost of changing a design or background.

RFIC materials & layers

The canonical 4 × 4 RFIC workspace has its own project, revision and transaction API at /api/rfic/array4x4. It uses the same runtime pairing and YAML transport. It does not require the antenna client-version header. The two existing designs remain separate: design_monolithic_on_die and design_single_die_aip.

1. Read GET /api/rfic/array4x4/readiness. Confirm capabilities.edit.ready and every required name in edit_operations. On an older runtime, an absent list means these new technology operations are unavailable; existing editing remains unchanged.
2. Read GET /api/rfic/array4x4/designs/{design_id}. Use its project.revision.design_revision_id as expected_revision_id.
3. Send one atomic YAML request to POST /api/rfic/array4x4/designs/{design_id}/transactions. Keep the idempotency key for retries of the same operations.

Materials support the existing finite-conductivity conductor and constant-complex dielectric models. Conductor conductivity must be positive; dielectric relative permittivity must be at least one, with nonnegative conductivity and loss tangent. Edited definitions declare provenance: user_defined_development and validity: user_defined_unqualified_constant_model. Kind/model changes, process-owned definitions and unsupported loss laws are rejected.

expected_revision_id: rev_0001 # replace with the current revision
idempotency_key: material-layer-example-1
operations:
  - op: create_development_material
    material_id: user_dielectric
    material:
      kind: dielectric
      model: constant_complex
      label: User development dielectric
      relative_permittivity: 3.2
      loss_tangent: 0.002
      provenance: user_defined_development
      validity: user_defined_unqualified_constant_model
  - op: assign_layer_material
    layer_id: die_ild
    material_id: user_dielectric
  - op: set_layer_thickness
    layer_id: die_ild
    thickness_m: 0.000012

A valid transaction returns HTTP 200 with status: applied or replayed, the canonical project, regenerated physical_model and affected-product invalidation. HTTP 409 reports a revision conflict; HTTP 422 reports a rejected edit with field-level issues. The entire prior revision survives either refusal. Requests are limited to 128 KiB and 256 operations; responses to 16 MiB.

These edits preserve stable object/port IDs and historical results. Technology-dependent products become stale; retained process geometry keeps its original source and cannot become current by relabelling. No numerical job starts, and no antenna dimensions are automatically tuned. Independent port definitions, arbitrary port impedance, full-wave boundaries and adaptive RFIC mesh are separate implementation work.

Errors & limits

Readiness returns actionable requirements. Transport failures return an error message and, where available, a structured code. Native failures are retained on the job with logs and partial evidence.

Execution settings include seconds, host_memory_bytes, device_memory_bytes, storage_bytes, time_steps and duration_ns. Use /catalog for defaults. Search budgets are capped at 128 evaluations and 14,400 seconds; native evaluation bounds and available resources may reject work earlier.

Budgets are admission and lifecycle controls. Sampled host/device memory peaks have coverage limits; native allocations and short-lived events may require separate diagnostics.

Results & evidence

Every admitted result is tied to its scene, candidate, solver and exact frequency samples. Complex values are pairs [real, imaginary] in s11 and impedance_ohm, with reference_ohm: 50. Public job records may use a scene_ref that points to the job’s authoritative scene.

Results include native execution evidence, the actual execution mode, fresh solve counts, phase timing and available resource measurements. Numerical session measurements cover the owned solver process tree; outer API/server memory and HTTP/YAML transport are outside that scope. Use job timestamps separately for API lifecycle wall time.

Inspection should distinguish process completion, native execution, numerical convergence and physical validation.