v2.20.0 Release Notes — Batch Job Tracking & Circuit Management¶

Release Date: 2026-02-18 Previous Version: v2.19.0 Commits: dad24679 → df0e4bb0

Overview¶

v2.20.0 extends the REST API with batch job monitoring and circuit management features. Batch Job Tracking provides real-time status polling for multi-simulation batches, while Circuit Management adds deep-copy cloning and parameter modification for loaded circuits. These additions complete the circuit lifecycle API for automation and parameter exploration.

New Features¶

1. Batch Job Tracking¶

Monitor the status of all simulations in a batch request — no manual per-simulation polling required.

Get Batch Status¶

Endpoint: GET /api/v1/simulations/batch/{batchId}

Returns aggregated progress and per-simulation status:

curl http://localhost:8080/api/v1/simulations/batch/batch-uuid-12345

Response:

{
  "batchId": "batch-uuid-12345",
  "totalSimulations": 20,
  "completed": 18,
  "failed": 1,
  "running": 1,
  "pending": 0,
  "overallProgress": 90,
  "done": false,
  "submittedAt": "2026-02-18T10:30:00Z",
  "simulations": {
    "sim-uuid-001": {
      "status": "completed",
      "progress": 100,
      "parameterSet": {"R1.resistance": 10.0}
    },
    "sim-uuid-002": {
      "status": "failed",
      "progress": 45,
      "parameterSet": {"R1.resistance": 50.0},
      "errorMessage": "Convergence failure at t=0.015s"
    },
    "sim-uuid-003": {
      "status": "running",
      "progress": 65,
      "parameterSet": {"R1.resistance": 100.0}
    },
    "sim-uuid-004": {
      "status": "pending",
      "progress": 0,
      "parameterSet": {"R1.resistance": 150.0}
    }
  },
  "failedIds": ["sim-uuid-002"]
}

Response Fields: - overallProgress - Weighted average of all simulations (0-100) - done - Boolean; true when all simulations complete or fail - failedIds - Array of simulation IDs that failed - simulations - Map of simulation ID to detailed status

Cancel Batch¶

Endpoint: DELETE /api/v1/simulations/batch/{batchId}

Cancels all running and pending simulations in a batch.

curl -X DELETE http://localhost:8080/api/v1/simulations/batch/batch-uuid-12345

Response: 204 No Content on success

2. Circuit Clone¶

Create a deep copy of a loaded circuit with optional parameter overrides — enables parameter sweeps without circuit file re-parsing.

Endpoint: POST /api/v1/circuits/{id}/clone

Basic clone (no overrides):

curl -X POST http://localhost:8080/api/v1/circuits/circuit-uuid-001/clone \
  -H "Content-Type: application/json" \
  -d '{}'

Clone with parameter overrides:

curl -X POST http://localhost:8080/api/v1/circuits/circuit-uuid-001/clone \
  -H "Content-Type: application/json" \
  -d '{
    "overrides": {
      "R_load.resistance": 12.0,
      "C_dc.capacitance": 4.7e-6,
      "L1.inductance": 100e-6
    }
  }'

Request Model (CircuitCloneRequest):

{
  "overrides": {
    "ComponentName.parameterKey": value
  }
}

Response: 201 Created

{
  "circuitId": "circuit-uuid-002",
  "name": "circuit_clone",
  "componentCount": 24,
  "parameters": {
    "simulationDuration": 0.02,
    "timeStep": 1e-6,
    "solverType": "trapezoidal"
  },
  "components": [
    {
      "name": "R_load",
      "type": "Resistor",
      "parameters": {
        "resistance": 12.0
      }
    }
  ]
}

Usage Pattern — Parameter Exploration:

# Load circuit once
response = requests.post("http://localhost:8080/api/v1/circuits/parse", files={"file": open("circuit.ipes", "rb")})
circuit_id = response.json()["circuitId"]

# Clone with different load resistance values
for r_load in [10, 50, 100, 200]:
    clone_response = requests.post(f"http://localhost:8080/api/v1/circuits/{circuit_id}/clone", json={
        "overrides": {"R_load.resistance": r_load}
    })
    cloned_id = clone_response.json()["circuitId"]

    # Submit simulation with cloned circuit
    sim_response = requests.post("http://localhost:8080/api/v1/simulations", json={
        "circuitFile": cloned_id,
        "simulationTime": 0.02,
        "timeStep": 1e-6
    })

3. Circuit Parameter Update¶

Modify simulation parameters (duration, time step, solver) for a loaded circuit without re-parsing.

Endpoint: PUT /api/v1/circuits/{id}/parameters

curl -X PUT http://localhost:8080/api/v1/circuits/circuit-uuid-001/parameters \
  -H "Content-Type: application/json" \
  -d '{
    "simulationDuration": 0.05,
    "timeStep": 5e-7,
    "solverType": "gear-shichman"
  }'

Request Model (optional fields):

{
  "simulationDuration": 0.05,
  "timeStep": 5e-7,
  "solverType": "gear-shichman"
}

Response: 200 OK

{
  "circuitId": "circuit-uuid-001",
  "name": "circuit",
  "componentCount": 24,
  "parameters": {
    "simulationDuration": 0.05,
    "timeStep": 5e-7,
    "solverType": "gear-shichman"
  },
  "components": [...]
}

Valid Solver Types: - backward-euler - Implicit 1^st order (stable, for stiff circuits) - trapezoidal - Implicit 2^nd order (balanced accuracy/stability) - gear-shichman - Variable order (best for variable dynamics)

Test Metrics¶

API Endpoint Count¶

Migration Notes¶

• No breaking changes from v2.19.0
• All new endpoints are additive
• Batch tracking requires batch creation via v2.19.0 POST /api/v1/simulations/batch endpoint
• Circuit clone uses same ParameterOverrideApplicator as v2.19.0 batch sweep

Known Limitations¶

• Circuit clone does not modify external file references (loss curves, etc.)
• Parameter update only affects simulation settings, not component parameters (use clone for component changes)
• Batch cancellation is asynchronous; may take 1-2 seconds to complete

Architecture Improvements¶

New Classes in gecko-rest-api:

• gecko.rest.api.dto.BatchJobStatus - Aggregated batch progress and per-simulation status
• gecko.rest.api.dto.CircuitCloneRequest - Clone request with optional parameter overrides
• gecko.rest.api.controller.BatchSimulationController - GET/DELETE batch endpoints
• gecko.rest.api.controller.CircuitManagementController - Clone and parameter update endpoints

REST API Endpoints Added:

• GET /api/v1/simulations/batch/{batchId} - Batch status and progress
• DELETE /api/v1/simulations/batch/{batchId} - Cancel batch
• POST /api/v1/circuits/{id}/clone - Deep-copy circuit with overrides
• PUT /api/v1/circuits/{id}/parameters - Update simulation parameters

Performance Notes¶

• Batch status polling (GET /batch/{id}) runs in O(n) where n = number of simulations (typically <100)
• Circuit clone is a deep copy operation; 50+ component circuits clone in <100ms
• Parameter update is O(1) for circuit parameter modification

Security Considerations¶

• Circuit clone respects same parameter path whitelist as parameter override (prevents arbitrary property access)
• Batch cancellation requires valid batch ID (no wildcard/regex matching)

Upgrade Path¶

Existing v2.19.0 deployments can upgrade without code changes. The new endpoints are additive and do not modify the behavior of existing endpoints.

See Also¶

• REST API Documentation
• Batch Simulation Examples
• Circuit Management Guide