cogitan

CLI + Python SDK for the Cogitan Surrogates API — run physics-simulation surrogate models on demand over HTTP. No models, solvers, or GPUs on your machine: you send inputs, our GPUs run a trained neural-operator surrogate, you get results back.

Cogitan is built for volume — sweeps of thousands to hundreds of thousands of simulations, run in seconds. If you need one answer, run a solver. If you need a parameter sweep, an optimization loop, or a design-space search, that's what this is for.

The thermal surrogate (live today)

Transient 2-D heat conduction. A Fourier Neural Operator trained on synthetic finite-element data (so no client data, no client IP touches the model):

• ~0.04% accuracy — validation relative-L2 of 0.000409 vs the full FEM solver.
• 21.8× faster than FEM on CPU, 100×+ on GPU — and it batches, so a whole sweep runs at once.
• ~500 simulations/second on the Economy tier; a 50,000-case sweep in well under two minutes.
• Valid envelope: conductivity 1–100 W/(m·K), boundary temperature 273–373 K, 0–4 heat sources, on a 64×64 grid.

Install

pip install cogitan

This gives you both the cogitan command and the import cogitan SDK.

Set up your key (once)

cogitan login
# Paste your Cogitan API key: cog_sk_********
# ✓ Saved to ~/.cogitan/config.json

Your key is stored in ~/.cogitan/config.json (locked to your user) and used automatically. Resolution order, first match wins:

1. --api-key flag (one-off)
2. COGITAN_API_KEY env var (CI / containers)
3. ~/.cogitan/config.json (the normal case)

Point at a non-default endpoint with cogitan login --base-url ... or COGITAN_BASE_URL.

Pick your speed (once)

Sweeps run on a speed tier. You choose the speed; we handle the hardware. Your choice is saved like your API key and used for every sweep:

cogitan speed              # show the current tier
cogitan speed fast         # set it

Tier	Feel	Price / simulation
economy	cheapest, far faster than CPU	$0.0005
fast	several times faster	$0.0015
max	fastest, for the biggest jobs	$0.003

Override per-run with cogitan sweep --tier ... or the COGITAN_SPEED env var.

Pricing is a fixed quote = price/sim × N, shown before you run and held against your prepaid balance. You're charged only on success; failures are refunded automatically. A 50,000-case Economy sweep is $25.

Run a batch sweep

Not sure where to start? Get ready-made starter files for any model:

cogitan template thermal
# ✓ wrote sweep.json   ✓ wrote cases.json   ✓ wrote cases.csv

Two ways to describe the work:

1. A sweep spec — give parameter ranges and a count; we generate N cases by Latin-hypercube sampling (compact, best for large N):

cogitan sweep thermal --spec sweep.json --out results.json

sweep.json:

{
  "n": 50000,
  "params": { "conductivity": [1, 100] },
  "base": { "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}] }
}

params entries that are [lo, hi] are swept; anything else is held fixed. base is merged into every case. Add "seed": 123 for reproducibility.

2. An explicit list of cases — one simulation per entry (your own design matrix), as JSON or CSV straight from a spreadsheet:

cogitan sweep thermal --params cases.json --out results.json
cogitan sweep thermal --params cases.csv  --out results.csv     # Excel-friendly both ways

cases.json:

[
  { "conductivity": 12, "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}] },
  { "conductivity": 47, "sources": [{"x": 0.3, "y": 0.7, "amplitude": 25000, "width": 0.10}] }
]

cases.csv — one row per simulation, columns = field names (cells containing JSON like [...] are parsed; empty cells are skipped):

conductivity,sources
12,"[{""x"":0.5,""y"":0.5,""amplitude"":30000,""width"":0.08}]"
47,

Fixed fields a CSV can't hold (nested sources/boundary shared by every case) go in a small JSON file merged into every row: --base base.json.

Results as a spreadsheet: pass --out results.csv and the per-simulation results flatten into columns (param.conductivity, max_temperature, ...) — opens directly in Excel. --out results.json keeps the full JSON.

cogitan sweep submits the job, shows the quote, then polls until it finishes and writes the results. To submit without waiting, add --no-wait and check on it later:

cogitan sweep thermal --spec sweep.json --no-wait
cogitan job <job_id> --out results.json

Run a single case

For one-off predictions (small jobs), cogitan run:

cogitan run thermal --in case.json --out result.json     # from a file
cogitan run thermal -p conductivity=50                   # inline params (JSON-parsed)
echo '{"conductivity": 50}' | cogitan run thermal        # piped stdin

cogitan describe thermal prints the model's input schema.

Commands

Command	What it does
cogitan login / logout / whoami	Manage and check your saved API key
cogitan speed [tier]	Get or set your default speed tier
cogitan template <model>	Write ready-made starter files (sweep.json, cases.json, cases.csv)
cogitan sweep <model>	Run a batch sweep (--spec, or --params JSON/CSV; --out .json/.csv)
cogitan job <id>	Check a sweep's status / download its result
cogitan run <model>	Run a single prediction
cogitan models / describe <model>	List the catalog / show a model's input schema
cogitan usage	Current credit balance + pricing
cogitan config / version	Show settings / print the version

Add --help to any command for details.

Python SDK

import cogitan

client = cogitan.Client()                      # key + speed from config/env automatically

# --- a batch sweep: submit and block until done ---
job = client.sweep("thermal", sweep={
    "n": 10000,
    "params": {"conductivity": [1, 100]},
    "base": {"sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}]},
}, tier="economy")
results = client.fetch_result(job)             # download the result JSON
print(results["sims_per_sec"])
for row in results["results"][:3]:             # one entry per simulation, params echoed
    print(row["params"]["conductivity"], row["max_temperature"])

# --- or drive the lifecycle yourself ---
job = client.submit_job("thermal", params=[{"conductivity": 12}, {"conductivity": 47}])
print(job["quote_usd"], job["balance_usd"])
final = client.wait_job(job["job_id"], on_poll=lambda j: print(j["status"]))

# --- a single case ---
result = client.run("thermal", {
    "conductivity": 50,
    "sources": [{"x": 0.5, "y": 0.5, "amplitude": 30000, "width": 0.08}],
})
result = client.thermal.predict(conductivity=50)        # namespaced sugar

Errors raise cogitan.APIError (with .status_code, .code, .request_id) or cogitan.NotConfigured if no key is set.

Local development

pip install -e .                               # from this directory
COGITAN_BASE_URL=http://localhost:8000 cogitan models