Simulation API

HX-SDP can dispatch physics simulations on GPU infrastructure and stream results into QTT-compressed storage. Simulation endpoints let you submit, monitor, and retrieve results for PDE solvers running inside the HolonomiX engine.

---

Submit simulation

POST /v1/simulation/submit

Request body

Field	Type	Required	Description
solver	string	Yes	Solver identifier (e.g., navier_stokes_2d, helmholtz_3d, poisson_2d)
namespace	string	No	Namespace for output storage (default: default)
params	object	Yes	Solver-specific parameters
output_key_prefix	string	No	Key prefix for stored results (default: solver name)

Example

curl -X POST https://gate.holonomx.com/v1/simulation/submit \
  -H "X-Api-Key: $HX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "solver": "navier_stokes_2d",
    "namespace": "cfd_runs",
    "params": {
      "n_bits": 10,
      "reynolds": 1000,
      "steps": 500,
      "dt": 0.001
    },
    "output_key_prefix": "ns2d_run_001"
  }'

Response — 202 Accepted

{
  "job_id": "sim-a1b2c3d4",
  "solver": "navier_stokes_2d",
  "status": "queued",
  "namespace": "cfd_runs",
  "output_key_prefix": "ns2d_run_001"
}

---

Check simulation status

GET /v1/simulation/status/{job_id}

Response — 200 OK

{
  "job_id": "sim-a1b2c3d4",
  "status": "running",
  "solver": "navier_stokes_2d",
  "progress": {
    "steps_completed": 142,
    "steps_total": 500,
    "elapsed_s": 28.4
  }
}

Status values: queued, running, completed, failed.

---

List simulations

GET /v1/simulation/list

Query parameters

Parameter	Type	Default	Description
namespace	string	all	Filter by namespace
status	string	all	Filter by status
limit	int	50	Maximum results

---

Retrieve simulation results

Simulation outputs are stored as regular HX-SDP entries. Use the standard GET and SERVE endpoints with the output key prefix:

# List stored fields
curl https://gate.holonomx.com/v1/list/cfd_runs?prefix=ns2d_run_001 \
  -H "X-Api-Key: $HX_API_KEY"

# Reconstruct a specific timestep
curl -X POST https://gate.holonomx.com/v1/serve \
  -H "X-Api-Key: $HX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "ns2d_run_001_vorticity_t500", "namespace": "cfd_runs"}'

---

Available solvers

Solver ID	Domain	Grid sizes	Description
poisson_2d	Elliptic PDE	512² – 16384²	Poisson equation with GPU-native CG
navier_stokes_2d	CFD	512² – 4096²	Incompressible NS with QTT-native operators
helmholtz_3d	Wave	512³+	3D Helmholtz with implicit diffusion
euler_2d	CFD	512² – 8192²	Compressible Euler with WENO reconstruction

Note

All solvers enforce a minimum grid of 512×512 (n_bits ≥ 9). Smaller grids are rejected.