Welcome to Converra

Converra helps you design high-temperature superconducting magnets and compare winding choices against a fixed specification. Search geometry and REBCO conductor options, inspect operating limits, and compare the modeled cost of eligible designs.

This handbook is the starting point for using Converra. It follows a study from requirements and conductor data to a calculated decision and a review package.

Converra 0.2.0 is the current workspace version. The handbook describes the current source and hosted workbench. Spreadsheet imports, draft recovery, diagnosis and scenario studies were added after the v0.2.0 desktop archives; build current source to use them on desktop. Python bindings currently require a source build.

Choose where to begin

The desktop, browser, CLI, Python and MCP interfaces use the same Rust engine. Browser calculations run in a background worker; desktop and CLI also support local directories and batch workflows.

What a calculated decision means

A passing screen means a declared model and sampling plan met the requirements it evaluated. Review material coverage, finer acceptance checks and unresolved engineering work before selecting a design. Converra retains PASS, FAIL, INCONCLUSIVE and NOT_EVALUATED separately so missing evidence stays visible.

Converra is developed by Avila Labs and released under the MIT license. Source, releases and issues are on GitHub.

Install and choose a workflow

Browser

Open converra.avilalabs.org. You can edit cases, import CSV/TSV/XLSX material tables, run searches and scenario studies, and download reports and review packages. Calculations run on your device in a Web Worker.

Draft recovery is specific to this browser on this device. Export a study workspace to keep a portable copy. Folder libraries, queues, directory comparisons and watch mode require desktop.

Desktop and CLI

Download an archive from GitHub Releases.

Extract and launch Converra or Converra.app. The CLI is optcoil; the local agent server is optcoil-mcp. Windows adds .exe. No Rust installation is needed for these binaries. Verify the archives against the release’s SHA256SUMS. Linux desktop needs a graphical session and working graphics drivers.

The v0.2.0 archives predate several workflows documented here. The hosted workbench and current source contain the newer features.

Build current source

Install Rust. The repository pins Rust 1.95.0.

git clone https://github.com/AvilaLabs/Converra.git
cd Converra
cargo run --release -p optcoil-app

For headless use, cargo run --release -- --help builds the default CLI package. The internal crate and executable names retain optcoil.

To serve a local browser build, install Trunk 0.21.14 and the wasm32-unknown-unknown Rust target, then run trunk serve in crates/optcoil-app.

Keep private input files in ignored customer-data/ and generated calculations in ignored runs/.

Your first study

Open the workbench. Its Measured conductor first study uses attributed Robinson SuperPower AP measurements at 21 K and a small racetrack search. Its prices are invented teaching inputs.

1. Review the inputs

Expand Applicability and work estimate. Read the field and aperture requirements, operating point, material class, width-transfer assumptions, price source and missing screens. Work estimates count sampling effort; they do not promise elapsed time or establish field coverage.

2. Calculate and read the decision

Run the study, then read Decision at declared inputs and prices. This example deliberately reaches an uncorrected self-field boundary: candidates remain INCONCLUSIVE, and the search cannot recommend a design. The diagnosis and named follow-up steps are the useful result.

Keep the declared bounds intact while learning. Raising a bound changes the question being screened.

For an example with a documented passing option, load benchmarks/coupled/oc-007.json from the source checkout. It evaluates 15 candidates and takes longer because it also refines the selected geometry and baseline.

3. Revise one choice

Use Revise or duplicate the case as a named alternative in Engineering study. Change one declared price, operating condition or winding choice, validate the revision, then run it. The previous completed result remains available for comparison.

Compare the changed inputs alongside the decisions. Equal costs can hide different requirements; a lower cost can result from relaxed constraints or changed material assumptions.

4. Save the study

Export a study workspace to preserve variants and historical results. Use Reports → Review package to collect the exact case, completed record, material dependencies and readable report. Browser export produces a tar archive; desktop creates a new directory.

A result without an eligible optimum still exports its diagnostic evidence, with procurement marked unavailable.

Next: read your results, then bring conductor data.

Read your results

Read the decision, individual checks and limitations before the cost total. A search can finish successfully as a computation while producing no eligible design.

Three levels to inspect

Candidate screening evaluates a geometry at the stated sampling plan. Inspect peak conductor field, critical-current utilization, geometric clearance and every configured screen. A sampled pass says nothing about locations the plan did not resolve.

Search and selection describe the campaign as a whole. A bounded or cancelled search may retain an incumbent without establishing an optimum. An unresolved comparison or a baseline that cannot pass its refined check can prevent a recommendation even when a candidate passes a coarse screen.

Acceptance and verification answer different questions. The acceptance path separately recomputes costs and screening checks, using finer sampling where declared. Its physics assumptions remain shared with the search. Offline verify checks input bindings, record structure and ledger arithmetic; physical validation needs suitable independent evidence.

Read a savings figure

Compare the baseline and candidate under the same requirements, material policy, fidelity and prices. Savings are the reduction in modeled total cost relative to that baseline. Synthetic prices support an illustrative comparison; a quoted price needs its source and commercial assumptions recorded.

Read the installed and purchased conductor lengths, manufacturing terms and missing checks alongside the percentage. Structural analysis, thermal design, quench protection and manufacturing qualification require their own evidence.

See benchmarks for worked interpretations and troubleshooting when a study cannot select a design.

Geometry and operating requirements

A case declares the engineering question: field requirement, clear aperture or good-field region, operating current and temperature, allowed winding choices, material bindings, numerical settings and costs. Set these before comparing designs.

Choose a supported geometry

The guided workbench builder authors supported racetrack and helix cases. Loaded cases expose structured revision controls and an advanced JSON editor for other declarations. A general CAD solid is not automatically a supported winding case.

For a non-planar path, bind the field map and its declared geometry/current convention. Coverage, interpolation and conductor orientation remain part of the screened problem. The helix benchmark documents this workflow.

Define what can change

The candidate grid bounds the search. Turn counts, tape counts, parallel strands and permitted geometry parameters are choices within that grid. Grading additionally declares the conductor specifications and allowed winding regions or interfaces.

Use consistent requirements when ranking alternatives. A larger aperture, lower field, different operating temperature or altered sampling gate changes the design problem. The study comparison displays these changes; scenario ranking rejects incompatible contracts.

Check applicability first

Use the workbench’s applicability panel or optcoil preflight case.json before dispatch. Resolve missing datasets and invalid declarations. Preflight checks input applicability and estimated workload; it cannot prove that the solved peak conductor fields stay inside the material domain.

Keep sampling and search limits explicit. Refined selection checks can reveal a limiting point that the coarse candidate screen missed.

Detailed schema and engine structure: architecture.

Conductor data and imports

Converra evaluates critical-current data against local conductor field, temperature and tape orientation. The usable domain belongs to each dataset. The bore field alone does not describe the peak field on the tape.

Embedded data

Embedded sources include attributed measured characterizations, a labeled model extension and published model-fit variants. Most measured tables cover approximately 20–40 K and fields up to 8 T, with distinct lower field limits and angular coverage. Higher-field fits and extensions are model-informed inputs.

Review the dataset’s source, measured bridge width, original tape width, measurement criterion and supported domain. Transferring bridge current to full-width tape requires declared assumptions. A signature establishes a provenance binding; it does not establish measurement accuracy or conductor qualification.

Import a table

Use File → Import spreadsheet / CSV for UTF-8 CSV/TSV or Excel XLSX. Select the worksheet, preview rows and map measured temperature, field, angle and critical current. Supply n-value from a column or an explicit constant.

Choose units for each quantity. Map nominal coordinates separately, or explicitly choose to reuse measured coordinates as the nominal grid. Record attribution, usage terms, material identity and measurement declarations. Current-per-width conversion uses the declared measured bridge width.

Imports are limited to 32 MiB. Invalid, duplicate or unsupported data requires correction; the importer does not invent metadata or extrapolate values. A validated import can be applied to a case or exported as a material bundle.

Attach all dependencies

A case binds each material by dataset ID and CSV SHA-256. The supplied source must match both. In the Materials view, resolve every base and graded tape dependency. CLI commands accept repeated bundle flags:

optcoil coupled-search graded-case.json \
  --dataset-bundle base.bundle.json --dataset-bundle grade.bundle.json \
  --output runs/graded.json

Metadata plus canonical CSV is also supported. An omitted/null metadata hash is computed; a declared mismatched hash is rejected. Review packages include all resolved dependencies.

Canonical columns, signed bundles and registry checks: dataset reference and vendor guide.

Costs, grading and procurement

The cost model combines installed conductor length, purchasing/scrap rules, assembly and declared joint or splice costs. Prices belong to the case; results retain whether they are synthetic, estimated, published or quoted.

Price the winding you actually declared

For a simple scrap model, purchased length is installed length multiplied by 1 + scrap_fraction. Each grade uses its own price per metre. Joint and assembly terms remain in the total even when a candidate uses less conductor.

With a piece policy, the ledger instead buys declared piece offerings and accounts for the resulting splices and remnants. Module boundaries and per-strand purchasing change those counts. Specify them explicitly before interpreting the cheapest offering.

Use grading deliberately

Assign conductor specifications to declared winding regions or permitted interfaces. Each specification retains its own dataset, price and material assumptions. Supply all external dependencies before running a graded case.

A cheaper grade can save material cost while increasing tape count, purchased length or transition costs. Inspect the regional allocation and complete ledger, then compare the same requirement and sampling plan.

Read the procurement outputs

The BOM contains installed and purchased metres per specification, turn ranges, geometry, joints/pancakes and reconciled ledger totals. Piece policies add offering, splice and remnant quantities.

A record without a passing eligible optimum cannot produce a purchasing design. Review export preserves that result with procurement unavailable. A modeled BOM or RFQ summary describes the declared design; supplier availability, lead times, tooling, insulation and splice qualification need their own inputs.

References: grading and BOM/piece policy.

Compare variants and scenarios

Use Engineering study to keep named alternatives, source data and historical calculations together. Duplicate a baseline, revise one declared choice, run the variant and compare its decision against the baseline.

Saving a workspace retains the study. Device-local recovery helps recover drafts; export remains the portable copy. Historical evidence stays attached after revision and is marked by its input bindings.

Sensitivity and conductor comparisons

Sensitivity sweeps vary declared operating inputs and show how the screening result responds. Dataset comparisons evaluate conductor/product alternatives under the study’s stated assumptions. Keep changed material domains and price sources visible when comparing costs.

Repricing a completed result answers an economic what-if. It does not automatically provide a new refined engineering recommendation. Graded or piece-priced studies require their corresponding per-spec declarations.

Explicit scenario studies

Current source and the hosted workbench provide What-if robustness study. Select comparable alternatives, retain the nominal row, and declare supplier-price multipliers, critical-current multipliers and temperature offsets. Preview the workload, then run.

Each row runs the bounded search at its original numerical fidelity. Unsupported material queries remain unresolved. Scaled critical-current data receives a synthetic sensitivity identity; it retains the source attribution without inheriting a measured-data claim.

Read scenario winners, changes of preferred alternative, acceptance checks and unresolved rows together. An unresolved alternative prevents a supported global ranking. Cost ranges and regret describe the choices and scenarios actually evaluated.

The scenario set assigns no probabilities. Editable defaults are illustrative what-ifs, and a stable winner across those rows is conditional on those assumptions.

CLI/MCP specifications and limits: scenario reference. Workspace format and history: engineering workspaces.

Export and review a design

A review package collects the calculation and the inputs needed to interpret and rerun it. Use Reports → Review package after a completed study.

The package includes exact case bytes, the record, a readable HTML report and decision summary, all resolved material bundles, and an artifact manifest. Eligible selections also include modeled procurement outputs. Browser exports a tar archive; extract it before using the CLI verifier.

From the CLI

optcoil review-package runs/design.json case.json \
  --output runs/design-review
optcoil verify-package runs/design-review

Choose a new destination. Export protects existing evidence from overwrite. The package README lists its rerun command, including repeated --dataset-bundle flags where needed; run that command from the extracted package directory.

When opening a saved record

A record does not contain every original input byte. Use Attach original case in Reports; the case’s byte hash must match the record before a rerunnable package can be exported. Load matching external material dependencies too.

Keep a saved study workspace when you want named variants and historical comparisons as well as one run’s review package.

What verification checks

Package verification checks artifact bindings, identities and modeled arithmetic. Acceptance checks separately recompute the selected design and baseline under the declared screening model. An engineer still needs to review material applicability and the structural, thermal, quench and manufacturing evidence relevant to the decision.

For a study with no eligible optimum, the diagnostic result remains reviewable. Its missing procurement output is an explicit consequence of that decision.

Command-line workflow

The executable is optcoil. With a source checkout, replace it with cargo run --release --; Cargo defaults to the CLI package. Examples below use repository-relative fixtures.

A small reference run

optcoil demo
optcoil preflight benchmarks/coupled/first-study.json
optcoil coupled-search benchmarks/coupled/first-study.json \
  --output runs/first-study.json

The first measured study intentionally yields an unresolved selection. The CLI writes its diagnostic record and exits nonzero because the search is not fully passing. Read the record before treating that exit as a software error.

A larger coupled search

optcoil coupled-search benchmarks/coupled/oc-007.json \
  --output runs/design.json
optcoil verify runs/design.json benchmarks/coupled/oc-007.json
optcoil report runs/design.json --output runs/design.html
optcoil bom runs/design.json --output runs/design.bom.json

OC-007 has measured conductor data and synthetic prices. Its search and refined checks can take several minutes. BOM export requires an eligible passing optimum.

Pass repeated --dataset-bundle flags to preflight, coupled-search and sensitivity for every external dependency. Output files are protected; use a new filename for each run.

Use optcoil --help and optcoil COMMAND --help for the installed version’s flags. The command families cover fields, material queries, sensitivity, dataset comparisons, reporting, review packages and source-build scenario studies.

Next: export and review. Detailed examples: first-study reference.

Python

The converra Python module wraps the Rust search engine. Cases, specifications and returned records use the same JSON contracts as the CLI. Wheels are not yet published on PyPI.

From the source checkout, create and activate a virtual environment, then build:

python -m pip install maturin
maturin develop --release --manifest-path crates/optcoil-py/Cargo.toml

Run and inspect a study

import json
from pathlib import Path
import converra

case_json = Path("benchmarks/coupled/oc-007.json").read_text()
record_json = converra.run_search(case_json, threads=2)
checks = json.loads(converra.verify_record(record_json, case_json))
print(checks)
Path("runs/python-design.json").write_text(record_json)
Path("runs/python-design.html").write_text(converra.render_report(record_json))

Create the runs directory first and use fresh output names. Inspect the returned verdicts as well as the verification checks. verify_record binds the case and checks the ledger; it does not independently validate physics.

Other operations

list_datasets lists embedded data. run_sensitivity evaluates a case and sensitivity specification. run_dataset_bakeoff compares datasets from a supplied bundle directory. verify_dataset checks a material bundle, with optional registry information.

The expensive run calls release the Python GIL. Bound calculations through the case’s search limits and thread option. Python cancellation is not exposed, and this binding does not expose every GUI/MCP workflow.

API details: Python binding reference and binding implementation.

Local MCP server

optcoil-mcp lets an MCP client operate a Converra study through typed local tools. It uses stdio and an explicit study directory. The GUI and server share the workspace format and engine operations.

Download the platform’s CLI/MCP archive, or build current source:

cargo build --release -p optcoil-mcp

Configure your client with absolute executable and workspace paths:

{
  "mcpServers": {
    "converra": {
      "command": "/absolute/path/to/optcoil-mcp",
      "args": ["--workspace-dir", "/absolute/path/to/study"]
    }
  }
}

Use .exe on Windows. Client configuration formats vary; the process arguments remain the same. Run one server per workspace directory.

A study through tools

Discover capabilities and datasets, create/import a study, create a named variant and attach its material dependencies. Use preflight_variant and diagnose_variant, then start_search. Poll get_job until completed, cancelled or failed. A cancellation request alone does not establish completion.

Inspect the result, compare variants and export a review package. Resources expose full inputs and records when tool responses return compact summaries. Completed evidence persists with the workspace.

Source builds also offer preview_robustness, start_robustness and scenario history. A proposed follow-up is unevaluated until calculated. The live-session cache only reuses verified unchanged calculations; reopening a workspace preserves history without seeding that cache.

Setup, complete tool list and budgets: MCP reference.

Models and supported domains

Converra couples a declared magnetic-field model to conductor critical-current data sampled along the winding. It screens the geometry and operating choices that the case and dataset support.

Field and material coverage

Planar racetrack, circular and line-and-arc paths have built-in field evaluation. Non-planar paths require a declared map. The finite-cross-section field model assumes its stated current distribution; agreement with another implementation tests that model’s calculation.

Measured conductor tables have dataset-specific field, temperature and angular bounds. Full-field magnitude, tape orientation and along-current fraction matter. An opt-in transverse bound is labeled as a bounded estimate and retains its own limits. Queries outside coverage stay unresolved.

Model extensions and published fits support sizing and sensitivity within their declared domains. Their rows are modeled values. Inspect the evidence class rather than interpreting a high-field number as a measured current limit.

Self-field and additional screens

Self-field policies depend on the case schema and declarations. Older uncorrected screens use a small self-field-ratio bound; newer uniform-transport policies apply a declared correction within their supported regime. A critical-state redistribution boundary can still produce INCONCLUSIVE.

First-order Lorentz-load and hoop-stress screens use declared load-path assumptions. Optional thermal-margin, AC-loss and quench screens evaluate configured bounds. They leave unsupported or unperformed engineering work visible.

Refinement and acceptance

Sampling resolution controls which local extrema a check sees. The acceptance path can evaluate the selected design and baseline with a finer plan. Coarse candidate success therefore does not promise refined success.

Cost recomputation is separate from search, but physical assumptions are shared. Use independent benchmark comparisons to assess the numerical evidence, then obtain the conductor, structural, cooling, protection and manufacturing evidence needed for your design.

Technical contracts: supported domains and technical overview.

Benchmarks and comparisons

Converra’s comparisons answer several different questions: whether its ledger is correct, whether a field kernel agrees with an independent implementation, and what a bounded search changes relative to a stated baseline. Read the inputs and acceptance scope before comparing headline figures.

Synthetic allocation: a hand-checkable optimum

OC-001 searches 4,096 grade/count combinations for three fixed modules. All prices and conductor capacities are invented. Fields are prescribed rather than recalculated from allocation.

The mixed allocation saves $108, or 11.59% of $932, under those assumptions. Full enumeration and the independent hand derivation establish the optimum within this finite synthetic problem. The result checks allocation, constraints and arithmetic; it does not predict customer savings.

A built magnet: Feather-M2

OC-010 compares equivalent tape consumption with CERN’s Feather-M2. The reference is approximately 190 m of 12 mm-equivalent tape, derived from published design quantities. The comparison targets the achieved 3.1 T operating specification.

The closest coarse-screened candidate uses 184 m: about 0.97 times the approximate reference. Its refined check remained INCONCLUSIVE at a tape-edge self-field point, and campaign-level gates did not produce a passing recommendation. This is a scoped conductor-quantity comparison with an approximate reference, rather than a qualified replacement design or a demonstrated cost reduction.

Independent field calculation: Bluemira

OC-011 sends the same declared geometry, ampere-turns and probe deck through Converra and an independent Bluemira kernel.

The historical finite-cross-section comparison reports maximum relative field-magnitude differences of 2.2 × 10⁻⁶, 2.8 × 10⁻⁶ and 4.1 × 10⁻⁶ across three optimum-cell probe sets. Its predeclared magnitude gate was 10⁻³, with a near-zero absolute floor and a separate direction gate. A relative difference of 2.8 × 10⁻⁶ is about 2.8 parts per million.

Both implementations use the same uniform-current physical model. The agreement supports that kernel on those inputs; it does not compare conductor qualification, optimization quality or complete engineering workflows. The historical records are referenced under ignored runs/; the newer workflow harness did not rerun Bluemira and found no installed independent runtime in its inspected environments.

Coupled cost refinement and a blocked helix

OC-008 records 22.792% lower modeled cost than the original OC-007 baseline after bounded refinement. The prices are synthetic and the percentage is conditional on that baseline and screening model.

OC-031 records no passing helix design in its declared candidate set. It identifies current-capacity and material-coverage blockers. Retaining this negative result helps show where the supported inputs stop resolving the problem.

Workflow comparison: what was actually measured

The workflow comparison compares Converra’s explicit-file CLI path with its shared-study API on three frozen fixtures. Both use the same inputs and one solver thread. It measures software operations and timings.

All base/revised records were semantically equal after removing only allowlisted time/runtime fields. All three fixtures ended with failed searches; no selected geometry or cost was produced. Internal agreement passes in those records are separate from search success.

The shared-session exact repeats took 0.022–0.055 s because they reused verified completed results. The CLI repeats took 46.034–118.069 s because they launched new processes and solved again. These figures compare cache reuse with fresh calculation; they cannot establish a fresh-solver speedup. The single host observation did not measure human setup or review effort.

How to read a competitive claim

There is currently no matched end-to-end benchmark against COMSOL, Ansys, Allsolve or another commercial platform in this evidence. A fair comparison needs the same requirement, materials, geometry, numerical fidelity, prices and acceptance criteria, with fresh calculations distinguished from cached work. The existing evidence supports the narrower numerical and workflow questions above.

Troubleshooting

Browser recovery belongs to one browser/device. Keep exported workspaces and review packages for portable studies. Cancellation can retain previous completed evidence; wait for the job’s final state before starting another calculation.

When reporting a defect, include the version or commit, platform, exact command/UI action, relevant verdict and a minimal shareable input. Remove private supplier and customer information before attaching files to GitHub Issues.

Contribute and cite

Contributions to measured conductor coverage, independent field checks, numerical methods and engineering workflows are welcome. Start with CONTRIBUTING.md.

Keep measured, fitted and synthetic inputs distinguishable. Preserve supported domains, benchmark contracts and all four verdicts. A new physical model or numerical contract needs an identified version and appropriate reference evidence.

Before submitting code, run the repository’s formatting, Clippy, workspace tests, WebAssembly check and browser-workflow gates. Handbook changes build with mdBook 0.5.4 and are checked for chapter membership, source references, links, navigation, search and mobile layout.

Report a study

Identify the source commit or release, exact case and material dataset versions, declared prices, model/sampling choices, baseline and result verdicts. Attach a review package when the data can be shared. State whether a reported number is a fresh calculation, a cached repeat or a historical observation.

Converra uses the MIT license. Conductor data and third-party dependencies retain their own terms and attribution. Check those terms before redistributing a package containing external measurements.

The roadmap, changelog and technical records provide development history. This handbook is the maintained user entry point; individual OC reports retain their historical scope.