Cogitan
Documentation menu

API reference

AQFP

Functional verdicts for AQFP cells (majority, buffer) on the MIT-LL SFQ5ee AQFP process, with the circuit-test decks behind them. Paths are shown as the hosted API serves them, under https://api.cogitan.ai/v1/fluxus; a local engine serves the same route under /api. GET routes are free on the hosted API; every POST consumes one call of quota.
GET

/v1/fluxus/aqfp/cells

engine path /api/aqfp/cells · free

Every served AQFP cell: knobs with units, defaults and served ranges, the drive, beta_arm and envelope limits, the Mondrian thresholds, model and feature versions, bar status and caveats (read from the heads, not re-typed), the margin refusals, the interface rule, the topology guard and the circuit test behind the label.

What it does, in full

Every served AQFP cell: knobs with units, defaults and served ranges, the drive, beta_arm and envelope limits, the Mondrian thresholds, model and feature versions, bar status and caveats (read from the heads, not re-typed), the margin refusals, the interface rule, the topology guard and the circuit test behind the label.

Request

No parameters.

Example

curl
curl -s "$FLUXUS_API/aqfp/cells" -H "Authorization: Bearer $COGITAN_API_KEY"

Example body: no parameters

What it refuses

  • never refuses; a head whose bundle does not load reports available false with the error

Responses: 200 Successful Response.

Validated for

fidelity metadata_of_surrogate_of_circuit_simulation

the served AQFP heads; see aqfp_predict. Simulation, not silicon

The full aqfp_cells card
POST

/v1/fluxus/aqfp/interface

engine path /api/aqfp/interface · metered

The iface-1 interface margins and flag for a design on their own: whether its output can drive a standard Blackburn cell (output margin, the rule), the input margin and the four hops, the threshold, and the head's call beside them. For a functional design the flag fields equal the ones /api/aqfp/predict serves; otherwise served_with_verdict is false and the flag is static physics with no measured record. A design the head refuses is refused with the same reason.

What it does, in full

The iface-1 interface margins and flag for a design on their own: whether its output can drive a standard Blackburn cell (output margin, the rule), the input margin and the four hops, the threshold, and the head's call beside them. For a functional design the flag fields equal the ones /api/aqfp/predict serves; otherwise served_with_verdict is false and the flag is static physics with no measured record. A design the head refuses is refused with the same reason.

Request

Body: AQFPPredictRequest

AQFP functional verdict from spec knobs.

No cir field, deliberately. A raw AQFP netlist carries no spec, and this head's features are dimensionless groups of named spec quantities, so a netlist path could only invent them.

paramstype map[string, number] | nullunit
iin_uatype number | nullunit uA
celltype "majority" | "buffer"unit default "majority"

Example

curl
curl -s "$FLUXUS_API/aqfp/interface" -H "Authorization: Bearer $COGITAN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"cell": "buffer", "iin_ua": 55.0, "params": {}}'

Example body: the request model's own example

What it refuses

  • every design is answered by the same path as /api/aqfp/predict, so it inherits that route's refusals: a knob outside the cell's served range, the chain gate latching below 0.35 Ic, a feature outside the fitted box, a design off the training manifold, kout or kd_over_kx moved, or a majority-only input on the buffer -> refused with the same reason

Responses: 200 Successful Response; 422 Validation Error.

Validated for

fidelity static_physics_margin

iface-1 threshold tested on fresh functional calls in a mixed circuit (simulation); see each cell's functional_caveat

The full aqfp_interface card
POST

/v1/fluxus/aqfp/netlist

engine path /api/aqfp/netlist · metered

The exact circuit-test decks behind a design's verdict: label v2's deck for the majority, the buffer chain deck (BUF-L1) for the buffer, at nominal excitation and with both supplies at 90%. Each leg carries deck (the label's deck byte for byte), josim_deck (the same plus .print lines for every gate's LQ current) and the label's time grid; the response adds the pattern, the expected bits, the read stage, the read times and the read rule in words, so the verdict can be reproduced. The head's own call is given beside it (prediction). A design the head refuses is refused here with the same reason (200, refused true, no decks); malformed inputs are a 400 as on /api/aqfp/predict.

What it does, in full

The exact circuit-test decks behind a design's verdict: label v2's deck for the majority, the buffer chain deck (BUF-L1) for the buffer, at nominal excitation and with both supplies at 90%. Each leg carries deck (the label's deck byte for byte), josim_deck (the same plus .print lines for every gate's LQ current) and the label's time grid; the response adds the pattern, the expected bits, the read stage, the read times and the read rule in words, so the verdict can be reproduced. The head's own call is given beside it (prediction). A design the head refuses is refused here with the same reason (200, refused true, no decks); malformed inputs are a 400 as on /api/aqfp/predict.

Request

Body: AQFPPredictRequest

AQFP functional verdict from spec knobs.

No cir field, deliberately. A raw AQFP netlist carries no spec, and this head's features are dimensionless groups of named spec quantities, so a netlist path could only invent them.

paramstype map[string, number] | nullunit
iin_uatype number | nullunit uA
celltype "majority" | "buffer"unit default "majority"

Example

curl
curl -s "$FLUXUS_API/aqfp/netlist" -H "Authorization: Bearer $COGITAN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"cell": "buffer", "iin_ua": 55.0, "params": {}}'

Example body: the request model's own example

What it refuses

  • every design is answered by the same path as /api/aqfp/predict, so it inherits that route's refusals: a knob outside the cell's served range, the chain gate latching below 0.35 Ic, a feature outside the fitted box, a design off the training manifold, kout or kd_over_kx moved, or a majority-only input on the buffer -> refused with the same reason, no deck

Responses: 200 Successful Response; 422 Validation Error.

Validated for

fidelity exact_label_deck

byte-identical to the bench label builder (bench/aqfp/cellpipe.py chain_deck), checked by tests

The full aqfp_netlist card
POST

/v1/fluxus/aqfp/predict

engine path /api/aqfp/predict · metered

Functional verdict for one AQFP cell on the MIT-LL SFQ5ee AQFP process.

What it does, in full

Functional verdict for one AQFP cell on the MIT-LL SFQ5ee AQFP process.

Returns the verdict, its conformal set, and an EXPLICIT refusal of every margin quantity with the reason attached. The served head is an INTERIM model (installed 2026-10-12, did not pass its own pre-set quality bar; model_status and functional_caveat say so with its measured record). It serves the phase 2e wide design range and refuses designs outside it, and designs below its envelope, by name. functional is null when the conformal set is not a single class: that is an escalation, not a missing value, and escalate says so. The set is class-conditional (Mondrian): functional iff p_functional >= 1 - q_pos, not functional iff p_functional <= q_neg. With the served thresholds it can never hold both classes, so an escalation is a set holding neither class (p_functional between q_neg and 1 - q_pos). Coverage is per class, measured on fresh designs; conformal.coverage_scope gives the figures. A functional answer also carries interface_to_standard_cells ('weak' or 'ok') with its margins, threshold and a sentence: whether the design's output can drive a standard Blackburn cell (iface-1, a static physics margin; the call and p are unchanged by it).

cell "buffer" (default "majority") is answered by the buffer head (fluxus.sfq.aqfp.buffer_head, installed 2026-10-18 after its pre-registered bar passed): same knobs and response shape, cell_type "aqfp_buffer", its own envelope, ranges, features and caveat; majority-only inputs are refused by name.

Request

Body: AQFPPredictRequest

AQFP functional verdict from spec knobs.

No cir field, deliberately. A raw AQFP netlist carries no spec, and this head's features are dimensionless groups of named spec quantities, so a netlist path could only invent them.

paramstype map[string, number] | nullunit
iin_uatype number | nullunit uA
celltype "majority" | "buffer"unit default "majority"

Example

curl
curl -s "$FLUXUS_API/aqfp/predict" -H "Authorization: Bearer $COGITAN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"cell": "buffer", "iin_ua": 55.0, "params": {}}'

Example body: the request model's own example

What it refuses

  • cell other than majority or buffer -> HTTP 422 from the request model
  • a knob outside the cell's envelope, the chain gate latching below 0.35 Ic, or a design off the training manifold -> abstained with the reason
  • kout or kd_over_kx moved from the training value -> abstained
  • buffer: a majority-only input (branch3_arm_ph, branch3_mid_ph, branch3_tie_ph, majority_merge, beta_src) -> HTTP 400 naming it
  • every absolute margin -> refused with the reason (margins_refused)

Responses: 200 Successful Response; 422 Validation Error.

Validated for

fidelity surrogate_of_circuit_simulation

fresh designs simulated with our AQFP oracle (circuit tests at 5 GHz, 4.2 K, 3 noise seeds); simulation, not silicon. Each cell's measured record is its functional_caveat

The full aqfp_predict card
POST

/v1/fluxus/aqfp/predict/batch

engine path /api/aqfp/predict/batch · metered

Predict many AQFP designs in one call.

What it does, in full

Predict many AQFP designs in one call.

results is positionally aligned with items, and each entry is exactly what POST /api/aqfp/predict returns for that design (its 200 body, or the {"error": ...} object its 400 carries), so a malformed value, an unknown cell or field, or a majority-only input on the buffer is an error in its own slot. A value that is not a finite number, or not a number at all, is refused for the whole request by the schema (422 naming items[i].params.knob). Over 2000 items the request is TRUNCATED with a clamped block; a deadline at the request budget stops the rest with a budget block. summary counts the calls and refusal kinds.

Request

Body: AQFPBatchRequest

Many AQFP designs in one call (cell per item).

celltype stringunit default "majority"
itemsrequiredtype list[AQFPBatchItem]unit

Object: AQFPBatchItem

One design in a batch. cell defaults to the batch's cell. Any string is accepted here and checked per item, so an unknown cell is an error in its own slot.

celltype string | nullunit
paramstype map[string, number] | nullunit
iin_uatype number | nullunit uA

Example

curl
curl -s "$FLUXUS_API/aqfp/predict/batch" -H "Authorization: Bearer $COGITAN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"cell": "majority", "items": [{"params": {}}, {"cell": "buffer", "params": {"lq_ph": 6.0}}, {"params": {"lq_ph": -1.0}}]}'

Example body: the request model's own example

What it refuses

  • every design is answered by the same path as /api/aqfp/predict, so it inherits that route's refusals: a knob outside the cell's served range, the chain gate latching below 0.35 Ic, a feature outside the fitted box, a design off the training manifold, kout or kd_over_kx moved, or a majority-only input on the buffer
  • a non-finite or non-numeric value anywhere -> HTTP 422 for the whole request

Responses: 200 Successful Response; 422 Validation Error.

Validated for

fidelity surrogate_of_circuit_simulation

the served AQFP heads; see aqfp_predict. Simulation, not silicon

The full aqfp_predict_batch card
GET

/v1/fluxus/aqfp/status

engine path /api/aqfp/status · free

Whether the AQFP heads can serve, and what they were fitted on. The top level is the default (majority) head; cells lists both served cells.

What it does, in full

Whether the AQFP heads can serve, and what they were fitted on. The top level is the default (majority) head; cells lists both served cells.

Request

No parameters.

Example

curl
curl -s "$FLUXUS_API/aqfp/status" -H "Authorization: Bearer $COGITAN_API_KEY"

Example body: no parameters

What it refuses

  • never refuses; a head that does not load says so with its error

Responses: 200 Successful Response.

Validated for

fidelity metadata_of_surrogate_of_circuit_simulation

the served AQFP heads; see aqfp_predict. Simulation, not silicon

The full aqfp_status card
POST

/v1/fluxus/aqfp/sweep

engine path /api/aqfp/sweep · metered

Sweep one or two knobs (any AQFPCellSpec field, or iin_ua) linearly from start to stop in n points around the base design, and return the call, p_functional and refusal (kind and reason) of every point, row-major (the last axis varies fastest), with a summary. n defaults to 21 and is clamped to 2..201 for one axis and 2..41 per axis for two, with a clamped block. A base design that is wrong everywhere (an unknown field, a majority-only input on the buffer, a malformed value not on a swept axis) is one 400, not a grid of errors.

What it does, in full

Sweep one or two knobs (any AQFPCellSpec field, or iin_ua) linearly from start to stop in n points around the base design, and return the call, p_functional and refusal (kind and reason) of every point, row-major (the last axis varies fastest), with a summary. n defaults to 21 and is clamped to 2..201 for one axis and 2..41 per axis for two, with a clamped block. A base design that is wrong everywhere (an unknown field, a majority-only input on the buffer, a malformed value not on a swept axis) is one 400, not a grid of errors.

Request

Body: AQFPSweepRequest

One or two knobs over a grid around a base design.

celltype "majority" | "buffer"unit default "majority"
paramstype map[string, number] | nullunit
iin_uatype number | nullunit uA
axesrequiredtype list[AQFPSweepAxis]unit at least 1 items, at most 2 items

Object: AQFPSweepAxis

One sweep axis: an AQFPCellSpec field or iin_ua, linear start to stop.

knobrequiredtype stringunit
startrequiredtype numberunit
stoprequiredtype numberunit
ntype integer | nullunit

Example

curl
curl -s "$FLUXUS_API/aqfp/sweep" -H "Authorization: Bearer $COGITAN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"axes": [{"knob": "lq_ph", "n": 27, "start": 4.0, "stop": 30.0}], "cell": "buffer", "params": {}}'

Example body: the request model's own example

What it refuses

  • every design is answered by the same path as /api/aqfp/predict, so it inherits that route's refusals: a knob outside the cell's served range, the chain gate latching below 0.35 Ic, a feature outside the fitted box, a design off the training manifold, kout or kd_over_kx moved, or a majority-only input on the buffer (per point)
  • a base design wrong at every point -> HTTP 400 once

Responses: 200 Successful Response; 422 Validation Error.

Validated for

fidelity surrogate_of_circuit_simulation

the served AQFP heads; see aqfp_predict. Simulation, not silicon

The full aqfp_sweep card

Generated from Fluxus 0.3.0 at commit b9aa57d on 2026-10-20 by python -m fluxus.docs_bundle.