Jobs and Batches

Lynx uses two related concepts for simulation work: batches and jobs.

Batch

A batch is the top-level unit of submitted work, created by a single POST /jobs call. It represents one Monte Carlo study. A batch has:

a unique UUID (batch_id)
a name you provide
a total job count
counters for completed and failed jobs
an overall status: Pending, Running, Completed, Failed, or Cancelled
a created timestamp

A batch is complete when all its jobs reach a terminal state.

Job

A job is one individual simulation run within a batch, created automatically by Lynx when you submit a batch. Each job gets its own sampled parameter set drawn from the dispersions you defined. A job has:

a unique UUID (job_id)
a reference to its parent batch_id
the sampled parameters for this run (run_config)
a status
retry tracking: retries, max_retries
a timeout: timeout_secs
timestamps: created_at, claimed_at, started_at, completed_at
the ID of the runner that claimed it: assigned_runner
an error message if it failed: error_message

Batch vs job

	Batch	Job
Created by	Your `POST /jobs` call	Lynx automatically
Granularity	One study	One parameter sample
Status endpoint	`GET /batches/{batch_id}`	`GET /jobs/{job_id}`
Results endpoint	`GET /batches/{batch_id}/results`	`GET /jobs/{job_id}/results`
Retries	Batches do not retry	Jobs retry up to `max_retries`

Submitting a batch

curl -sS \
  -X POST https://api.lynx.tetryx.io/jobs \
  -H 'content-type: application/json' \
  -d '{
    "name": "spacecraft-analysis-v1",
    "config": {
      "simulation": {
        "name": "Spacecraft Mission Analysis",
        "version": "1.0.0",
        "duration_minutes": 120
      },
      "monte_carlo": {
        "runs": 500,
        "sampling_method": "latin_hypercube",
        "seed": 42
      },
      "dispersions": {
        "mass_kg": {
          "distribution": { "type": "normal", "mean": 2500.0, "std_dev": 125.0 },
          "units": "kg"
        },
        "drag_coefficient": {
          "distribution": { "type": "uniform", "min": 0.28, "max": 0.34 },
          "units": ""
        }
      },
      "compute": {
        "container": {
          "image": "your-org/simulation:latest",
          "cpu_request": "2000m",
          "memory_request": "4Gi"
        },
        "max_parallel_jobs": 20,
        "job_timeout_seconds": 3600
      },
      "early_termination": {
        "enabled": true,
        "check_frequency_hz": 10.0,
        "conditions": [
          {
            "variable": "battery_state_of_charge",
            "condition": "< 0.1",
            "description": "Battery critically low"
          }
        ]
      },
      "telemetry": {
        "sampling_rate_hz": 10.0,
        "variables": ["altitude", "velocity", "battery_state_of_charge"],
        "storage": {
          "s3_bucket": "your-telemetry-bucket",
          "s3_prefix": "spacecraft/",
          "compression": "gzip"
        },
        "buffer_flush_interval_seconds": 30
      }
    }
  }' | jq

Use runs_override to cap the run count without changing your config — useful for quick validation:

{
  "name": "quick-test",
  "runs_override": 3,
  "config": { ... }
}

Monitoring a batch

# Batch status with per-status job counts
curl -s https://api.lynx.tetryx.io/batches/<batch-id> | jq

# All terminal results for the batch
curl -s https://api.lynx.tetryx.io/batches/<batch-id>/results | jq

The status response includes:

jobs_by_status — job count for each status (Pending, Running, Completed, Failed, etc.)
throughput_jobs_per_minute — current processing rate
estimated_completion_time_mins — time remaining estimate, if computable

Sampling methods

Method	Description
`latin_hypercube`	Stratified sampling — best coverage with fewer runs
`monte_carlo`	Pure random sampling
`quasi_monte_carlo`	Low-discrepancy sequence sampling

Latin Hypercube Sampling (latin_hypercube) is recommended for most studies. It produces better parameter space coverage than random sampling with the same number of runs.

Getting Started

Runners

Authentication

Tutorials

Jobs and Batches

Batch

Job

Batch vs job

Submitting a batch

Monitoring a batch

Sampling methods

​Batch

​Job

​Batch vs job

​Submitting a batch

​Monitoring a batch

​Sampling methods

Batch

Job

Batch vs job

Submitting a batch

Monitoring a batch

Sampling methods