mcg_quote
Price a simulation. FREE: no hardware starts. Returns quote_id, quote_hash, tokens, rate_card_version, wall_s, expires_at, the plan, and record: {traced: true, node, node_uid, map_version (the openmaterials graph version the node is pinned at; the commons map version is published at openmaterials.ai/data/version.json), material (the material the pinned conditions name: what the run computes)} when the completed run's OpenMaterials record is keyed on that public map node (measured instances cite the method that ran), else {traced: false, reason}; read it before you spend. The price is a binding ceiling: never more than this. mcg_run accepts only this quote_id with this quote_hash before expires_at and REJECTS a stale hash (quote_mismatch) or an expired quote (quote_expired). Arms, exactly one: kind from mcg_catalog (spec passed through verbatim, spec.params set the price, engine overrides the default only with a known engine id); external_frontier, an OpenMaterials external-solve envelope from mcg_catalog's graphs (also returns request_id, plan_digest and the compiled plan; an envelope not byte-equal to a supported graph REJECTS with unsupported_graph); draft_id (see the parameter). Also returns app_url, the owner's page in the app (for the human, never fetched by the agent) and, on the kind arm, warnings: the inputs the app cannot render without (material or structure_xyz, study); pass them. accuracy_study needs no hardware_contract up front: the reply's contract_source says whether the run binds this simulation's published contract (published) or the labeled default synthetic one (default_synthetic).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Simulation kind from mcg_catalog, e.g. bulk_kappa. | |
| name | Yes | A human label for the simulation. | |
| spec | No | The spec object, e.g. {params: {...}, spec_yaml: '...'}. params drive the price. interface_tbc: params.production_steps and params.equilibration_steps set the NEMD budget (the run total across all interfaces) within the bounds the reply's certification.settable states (a refused run's summary.next names the key to raise); the price follows the budget. | |
| study | No | The study (project) this simulation belongs to, by exact name; created if absent. Every quote for one investigation should name the same study so the app groups them together. | |
| engine | No | Optional engine id override (rejected if unknown). | |
| target | No | Run on one of your connected clusters (see mcg_clusters) instead of the cloud: hardware cost 0, gate fee per the rate card and plan, wall time includes the scheduler's queue-wait estimate. The cluster's status must be connected. | |
| draft_id | No | Third arm: price a draft that mcg_stage created and whose inputs have been uploaded (refuses with inputs_missing while any declared input is absent). Also re-prices an already-quoted simulation, after its quote expired or to reproduce a run (pass the run's quote_id, its simulation_id): it clones the spec, the map pin and the staged inputs (not contract files, nor structure files the engine does not read; more than 25 inputs refuse) and returns the clone's fresh quote_id (reply carries requoted_from, and rerun_notes naming skipped inputs and structure overrides). Mutually exclusive with every other argument but name and target. | |
| material | No | Kind arm only: the material or formula being simulated (e.g. Si, MoS2). Also selects the reference structure. On a traced run whose engine fixes its own conditions it must match the spec's material. | |
| conditions | No | Kind arm only: physical conditions as key/value pairs, e.g. {T: 300}. Values are numbers, strings or lists of up to 16 of them, except on an adapter engine, which runs them: there any value its conditions schema allows (lists, booleans, null) over the keys it declares, judged at quote. On a traced run whose engine fixes its own conditions, a key or value its record does not hold is refused; the error names what to send or omit. | |
| max_tokens | No | Graph arm only: quote-time hard ceiling; a quote above it REJECTS (never clamps). | |
| structure_xyz | No | Kind arm only: the simulated structure as extended-XYZ text; staged as the input structure.xyz so the app renders the exact geometry (takes precedence over the material reference). | |
| external_frontier | No | The OpenMaterials #110 external-solve envelope, verbatim. Mutually exclusive with kind/spec/engine. |