Welcome to FARIS

FARIS, the Fusion Analysis and Reactor Integration Simulator, follows a fusion plant from 3D neutron transport to thirty years of operation. It shows how a blanket and shield design changes tritium breeding, magnet exposure, component replacements and net electricity year by year, and how sure those numbers are.

This handbook covers FARIS 0.1.0.

This release is a demo

FARIS 0.1.0 is a deliberately narrow demonstration, complete for one study: an ARC-inspired tokamak in four arrangements, from transport to thirty years of operation with uncertainty. The full product widens the geometry and adds activation and peak magnet fluence. Where FARIS is going lists what comes next.

Research screening only

FARIS results are not a licensing, safety or design basis. Every number is labelled as calculated, authored, literature, conditional or not evaluated. Reading the numbers explains each label. The statement is in the bottom bar of every step and in every export.

What the demo studies

One compact D-T tokamak, ARC-inspired, with 525 MW of fusion power, in four arrangements:

• Two blanket/shield allocations inside the same radial build.
• For each allocation, a finite outboard service port, and a matched port-free control.

The study asks one question: what changes when you move thickness from the neutron shield to the breeding blanket?

Start here

Download and verify the Linux package, then take the tour. You do not need OpenMC, nuclear data or a network connection to explore the recorded study.

Then read one chapter for each step of the workspace: Design, Simulate, Operate, Compare and Evidence. Read Reading the numbers and Scope and limits before you quote any result.

Find help

Use the search button or press / to search this handbook. Troubleshooting covers the messages the app shows. Report reproducible problems through GitHub issues, with your version and the message you saw.

Download and verify

Requirements

• A Linux desktop session with working graphics drivers.
• python3. The launcher and the verifier are Python scripts.
• Free temporary space: about 0.9 GB to open the study, because launch.sh unpacks the Core evidence (823 MB) into a private temporary folder, and about 2 GB for verify.sh. Both check the exact amount before they start. The package’s own README.md explains the sums.

You do not need OpenMC, nuclear data or network access to explore the recorded study. Only Linux is built and tested. Windows and macOS builds have not been tried.

Download the package

Download the Linux package, FARIS-0.1.0-linux-x86_64.tar.gz (112 MB), and SHA256SUMS from the 0.1.0 release. Check the archive, then unpack it:

sha256sum -c SHA256SUMS
tar xzf FARIS-0.1.0-linux-x86_64.tar.gz

The package holds four recorded transport cases, their Core evidence and the allocation sweep.

Verify it

From the package folder, run:

./verify.sh

This is optional. It checks the package from a relocated copy, rechecks every recorded byte and the Core receipts, and takes a while. It also confirms that a deliberately changed copy is rejected.

Open the recorded study

./launch.sh

launch.sh checks the hashes of the bundled programs and files, then opens the app with all four cases loaded. It keeps the unpacked Core evidence in a private temporary folder until the app closes.

The bundled programs are hash-pinned but not signed. A matching hash shows the bytes are the ones recorded in the package. It does not show who made them.

Build from source

You can build FARIS yourself with Rust. The repository README has the pinned toolchain, the build commands and the Linux packages the graphics stack needs. A source build opens an embedded geometry demo unless you give it a study. The recorded study comes with the package.

Next: take the tour.

Take the tour

Start the app

From the package folder, run ./launch.sh. The first time the app starts without a study file, it plays a 12-stop tour of the recorded study. It takes about a minute.

Use Next (or the Right arrow, or Enter) and Back (Left arrow) to move. Choose Skip tour (or press Esc) to leave. Finishing or skipping writes a marker file, so the tour does not play again. The marker is tour-completed in a faris folder under $XDG_CONFIG_HOME, or under ~/.config when that is not set.

Choose Tour in the top bar to replay it. Start the app with --tour always or --tour never to override the default.

The five steps

The workspace has five steps. The top bar has one button for each, and the keys 1 to 5 switch between them.

The left panel shows the controls of the current step. The right panel is the Outliner, where you show or hide components, and the Properties of the selected component. The centre is the 3D viewport. The bottom panel is the timeline, or the comparison on step 4.

Move in the viewport

• Drag to orbit.
• Shift-drag to pan.
• Scroll to zoom.
• Click a component to select it.

Frame scene resets the camera. Cutaway is a display option only. It does not change the model or any reported volume.

Change the interface size

Choose Interface size in the top bar. It offers 100, 125, 150, 175 and 200 per cent, and scales text, controls, panels and plots together. Ctrl/Cmd + and − adjust it; Ctrl/Cmd 0 resets it. The 100 per cent setting follows your desktop’s display scaling. To start larger, pass --interface-scale 1.25. The allowed range is 0.75 to 2.

Try three things

1. Press 3. Move Magnet service limit and watch the timeline.
2. Press 4. Read What changes first, then the flags.
3. Press 5. Read why the scientific verdict reads NOT_EVALUATED.

Next: Design: the plant in 3D.

Design: the plant in 3D

Press 1 to open the Design step.

The model

The viewport shows the plant as concentric shells from the first wall to the magnets. In FARIS the 3D view is the transport model: what you see is what the transport calculation used. The geometry is idealised. It is a full torus of concentric layers with one outboard port, not the published ARC design. Scope and limits says what that leaves out.

The plant has a major radius of 3.3 m and a radial build of 1.20 m. Fusion power is 525 MW.

Choose the arrangement

Port has two choices:

• With outboard port. One finite outboard service port, a 0.30 m × 0.30 m rectangular duct through the whole radial build. It has no shield plug. It is a bounding streaming case, and it is the 3D feature the magnets behind it feel most.
• No port (matched control). The same plant without the port.

Allocation lists the blanket/shield splits of the recorded study. The two arrangements you compare throughout the handbook are:

A radial-build bar shows the layers. Outlined layers are the ones that change between allocations. Look at it first.

Inspect a component

Click a component in the viewport, or select it in the Outliner, to see its Properties. Tick or clear the boxes in the Outliner to show or hide components.

Plant inputs (major radius, radial build, fusion power) carry the badge authored. They are assumptions written for this scenario. Sources and assumptions lists the cited literature and the authored assumptions behind them.

Next: Simulate: transport results.

Simulate: transport results

Press 2 to open the Simulate step.

Read the transport card

For the selected arrangement, the transport card shows:

• Tritium breeding: H3 atoms per source neutron.
• Magnet-region mean flux.
• Total nuclear heating.
• The number of histories.

Each value carries its Monte Carlo standard error. The recorded runs use 10 million histories for the port cases and the sweep, and 30 million for the port-free controls. Reading the numbers explains the standard errors and the badges.

The transport result is labelled “cold-data surrogate · NOT_EVALUATED”. Scientific qualification is not evaluated, even for completed transport, because the materials are surrogates and the data are cold. Hover the label for the reason, and read Scope and limits for what would settle it.

Colour the 3D model

The field-view menu in the viewport controls colours the model:

Flux colours use a fixed logarithmic scale, so arrangements are directly comparable. Each displayed value is a volume average over a mesh bin, including void. The mesh does not resolve point peaks. Gray bins have no samples. Desaturated bins have more than 30 % relative standard error. Neither treatment gives a zero-flux bound or a total uncertainty.

Transport fields use the recorded source strength and stay fixed during outages. Component colouring shows region averages, not a field inside a component.

Open Reference-source energy-group spectra to see the recorded neutron and photon flux spectra. They are flux spectra, not deposited-energy spectra.

Run new transport

Run and review transport can run new OpenMC transport. It needs your own OpenMC and data, set under Transport configuration. The recorded study does not need it. See Run your own transport.

Next: Operate: the 30-year history.

Operate: the 30-year history

Press 3 to open the Operate step. It edits the operating assumptions and recalculates the 30-year history of every arrangement and, when present, of the allocation sweep. The history follows magnet and blanket exposure, replacement outages, tritium inventory and net electricity.

Start with the preset menu, then move the sliders and watch the timeline.

Choose a preset

Hover a preset to see what it is and its key numbers.

Ask what if

Under What if…, each slider edits one assumption. Each edit cancels any running calculation and recalculates after a short pause. A row shows an edited badge and a revert button once you move it away from the preset.

• Magnet service limit: 10²¹ to 10²³ n/m², logarithmic, with the literature value marked and a reset button.
• Magnet replacement duration: 14 to 365 days.
• Blanket service limit: 10²⁵ to 10²⁷ n/m².
• Tritium recovery fraction: 0 to 1.
• Processing delay: 0 to 7 days.
• Thermal-to-electric efficiency: 0 to 1.
• Opening usable fuel / kg.

A row appears only when the preset declares it. Revert all to preset undoes every edit. Recalculate history is a manual fallback.

All of these values are authored or literature screening values. They are not material allowables or measured plant data. Service limits, outage durations, recovery fractions and efficiencies stay conditional on what you set.

Magnet limits per region

The magnet limit applies to fast fluence averaged over each of three regions:

• Inboard: the inboard half of the magnet.
• Outboard: the outboard half, outside the port sector.
• Port sector: the 20° sector of the outboard half behind the port.

Fluence is each region’s fast flux times operating time. The first region to reach the limit triggers the replacement, and the event names it. Replacing the magnets resets the exposure of every region. One slider moves all the region limits together.

FARIS reports regional averages, not the local peak. A hot spot inside a region can reach the limit sooner than the average does. The port-sector figure is the one most likely to understate it.

Read the timeline

The bottom panel plots one quantity for each arrangement. Choose it from:

• Magnet fluence, toward its service limit.
• Electricity, cumulative signed net electricity.
• Tritium, usable inventory.
• Full-power years, cumulative.

Click an arrangement chip to show or hide it. The one drawn in 3D is drawn thicker. Click or drag on the plot, or use the calendar years slider, to scrub through time. Scrubbing selects the computed snapshot at or before the requested time. Events are never interpolated across. In the Accumulated component fluence view, the 3D colours follow the year you scrub to.

Jump to a calculated event… lists every event: tritium imports, processed tritium released, operation started and stopped, fuel-limited stops, planned outages, service limits reached, and replacements starting and completing.

The headline row shows:

• Year.
• State: Operating, Magnet replacement, Component replacement, Planned outage, Fuel-limited or Stopped.
• Usable tritium, with the amount still in processing on hover.
• Net electricity so far.
• Magnet swaps so far.
• Next magnet swap.

Replacement outages and planned outages are authored in duration and timing. The planned outages are illustrative. They are not an availability estimate. Select a component in the Outliner to see its accumulated fluence, replacements completed, trigger and operating events.

Tritium and net electricity

Usable tritium follows breeder production, D-T burn, imports, processing delay, process loss and decay. It is conditional on the authored recovery fraction and delay.

Net electricity is gross output minus auxiliary load under authored energy assumptions. It is unavailable when no total nuclear-heat response is bound to the transport run. The ledger is not a coolant or thermal-cycle calculation.

Conditional sensitivity

The collapsed section Conditional sensitivity runs 27 full-history reruns. Recovery is 0.90, 0.95 and 0.99. Processing delay and the service limits are each ×0.5, ×1 and ×2. These are authored probes around the preset. They are not uncertainty bounds.

Next: Uncertainty ensembles.

Uncertainty ensembles

An ensemble carries the Monte Carlo sampling uncertainty of the transport through the 30-year history. You see it on the Operate step, under Uncertainty in the history.

How it runs

The app starts an ensemble for each arrangement in the background once the history settles, the selected arrangement first. You do not start it by hand.

• It can be cancelled. Any edit that changes the history cancels it.
• Nothing partial is shown.
• Finished ensembles are reused when the inputs are identical.
• The ensembles are saved in a study file, so a reopened study does not recompute them.

Under Samples, choose 200 or 1000. 1000 gives narrower sampling error and takes about five times longer. For 200 samples of four arrangements, expect minutes. The same seed gives the same result at any thread count.

What it does

FARIS draws the driving rates from a multivariate normal distribution. The rates are the breeder H3 per source neutron, the component fluxes and the heating. The distribution uses the recorded transport means and the covariance between them, so correlated quantities move together. FARIS runs the deterministic history once for each draw and summarises the spread. Method has the details.

What you see

• Each continuous output shows its nominal value beside the median and the 5 to 95 per cent range (P5 to P95). The range is a 90 % range. Each quantile has a distribution-free 95 per cent confidence interval, where enough samples exist.
• Discrete outputs, such as swap counts, show the share of samples with each value, with Wilson 95 per cent intervals.
• For a magnet with region limits, the first-trigger line says which region reached its limit first, for example “Magnet swap triggered first by: port sector in 97 % of samples, inboard in 3 %”.
• The timeline gets a shaded P5 to P95 band, labelled “bands: P5–P95, transport sampling only”.
• In Compare, paired differences use the same sample index in both arrangements. The pairing is valid only for independent transport runs.

A share of samples with a given swap count describes sampling noise. It is not a lifetime estimate.

The 1 per cent rule

A draw with a physically impossible rate, such as a negative rate or a non-positive heating power, is rejected and redrawn. If rejections exceed 1 per cent of accepted samples, the ensemble is not evaluated. The result states the rejection percentage and the next step: run more histories or use variance reduction. No summary is produced.

A transport record without covariance is also not evaluated. Independence is never assumed. The result says to rerun transport with this FARIS version to record the batch-resolved results.

What it does not include

The ranges cover transport Monte Carlo sampling uncertainty only. They do not include nuclear-data, geometry, material or model-form uncertainty, the tritium half-life, or any authored assumption. The true uncertainty is larger. The section carries the line “Transport Monte Carlo sampling uncertainty only, not nuclear data, model or assumption uncertainty.”

From the command line

faris history ensemble --assumptions A.json --rates R.json --output E.json \
  --samples 200 --seed 1 --threads 4

--samples is 1 to 2000 and defaults to 200. --seed and --threads are optional. An ensemble that is not evaluated is written and the command exits 0, so read the status field of the output. See Command line.

Next: Compare and the allocation sweep.

Compare and the allocation sweep

Press 4 to open the Compare step. The bottom panel shows Compare the four recorded arrangements. Drag the panel’s top edge to resize it.

The four arrangements

The panel has one column for each allocation, Reference (0.45 m blanket, 0.45 m shield) and Breeder-heavy (0.55 m, 0.35 m), and one row for each port setting, With port and No port. Each cell shows breeding, magnet flux, magnet swaps over the horizon, the first swap, lifetime net electricity and final usable tritium. Transport rows carry Monte Carlo standard errors. History rows are conditional on the operating assumptions you selected.

What changes

What changes lists four contrasts. Each row is the second arrangement minus the first:

• Breeder-heavy − Reference, with port.
• Breeder-heavy − Reference, no port.
• Port − No port, reference.
• Port − No port, breeder-heavy.

Columns give the change in breeding, magnet flux, swaps, first swap and net electricity. A one-line takeaway is written from the current numbers. Read this table first. Bar charts of lifetime net electricity and magnet swaps follow.

The 2σ flags

Each transport difference carries a flag. FARIS compares the difference with 2·√(SE₁² + SE₂²), where SE₁ and SE₂ are the two standard errors.

• “beyond 2σ sampling noise” means the difference exceeds that.
• “within 2σ sampling noise” means it does not.

The runs use different seeds and their covariance is not modelled. So the flag is a screening aid, not a significance test. “Beyond 2σ sampling noise” says nothing about nuclear data, geometry or model form.

Uncertainty in the history comparison

When the ensembles are ready, this section shows each contrast as a paired difference, sample by sample, with its range and the share of pairs where one arrangement is below, equal to or above the other. A contrast that cannot be compared says why and what to do. See Uncertainty ensembles.

The allocation sweep

Below the contrasts is the Allocation sweep, a set of seven recorded transport runs. They keep the same radial envelope and move thickness from shield to blanket. Each is an independent run with its own seed.

Move the Allocation slider through the splits. It shows the blanket and shield thickness of the selected point. Three charts show breeding, magnet flux and the histories. Their bars are sampling error only.

What the sweep shows lists the findings the recorded runs support. Statements about transport carry the badge calculated. Statements about replacements and electricity carry conditional on the selected preset, because they come from the operating history under authored assumptions. Transport uncertainty is not propagated into them.

Next: Evidence and Avila Core receipts.

Evidence and Avila Core receipts

Press 5 to open the Evidence step. It shows what Avila Core checked.

Three separate lines

Compilation, run readiness and the scientific verdict are separate lines. The scientific verdict reads NOT_EVALUATED. It stays that way because the transport uses cold-data surrogate materials and no qualification has been evaluated. Scope and limits lists what would change that.

Receipts

Studies run through Avila Core, which records hash-bound receipts. Each receipt binds a result to its exact inputs.

A saved Core workflow reads “executed and verified” when its receipts were rechecked on opening. That states the workflow ran. It does not state that the design works.

If the saved receipts cover only the loaded assumptions, a badge reads “receipts cover the loaded assumptions”. Choose Use the covered assumptions to switch to them. The receipts do not cover other presets or edited values.

Receipts not included

By default a .faris file records the Core evidence archives by name and hash and does not store them. The study opens fully. The Evidence step then says “Core receipts not included”, with the reason and the next step. Study files (.faris) explains how to supply the archives.

Compile and run

Compile study in the top bar and Run bound study stages need an Avila Core executable. Choose it under Compiler settings, or start the app with --core. The recorded package supplies one.

Compilation, run readiness and scientific assessment stay separate lines here too. A successful compile or run is not a scientific verdict.

Next: Study files (.faris).

Study files (.faris)

A .faris file is one saved study. It holds both arrangements (with and without the port), the recorded transport, the allocation sweep, the operating assumptions, any finished uncertainty ensembles, and the view you left open: the step, preset, what-if values, year, field view, history tab, and selected arrangement and allocation.

Calculated histories are not stored. They recalculate on opening, in about a second.

Open a study

Open a file in any of these ways:

• Choose File > Open… (Ctrl+O).
• Drop the file on the window.
• Pass it on the command line: faris-app demo.faris.

The window title shows the file name, with a dot after it when the view differs from what was saved.

Save a study

Choose File > Save (Ctrl+S) or Save as… (Ctrl+Shift+S). Save is greyed out, with a reason on hover, when nothing recorded can be saved. A study started from your own transport run records cannot be saved.

What is checked

Recorded files are stored byte for byte and checked by hash on every open. This keeps the Core receipts’ “unchanged since checked” guarantee through a save. A damaged file is refused, and the message names the damaged part. A file is also refused if a size is wrong, if it uses an unsupported encoding, or if its version is not major version 1.

Run this to see which part of a file fails:

faris study-file verify demo.faris

Referenced or packed evidence

By default the Core evidence archives (about 55 MB for the demo) are recorded by name and hash and are not stored. The study opens fully without them. Its Evidence step says “Core receipts not included”, and why, and what to do.

To use the archives, put them next to the file at the recorded relative paths and reopen it. For example, port/archives/reference-case.tar.gz goes at that path beside the file when it sits at the package root. Archives found there are checked against their hashes and used. One whose hash differs from the record is reported and never used.

Or tick Include Core evidence in saved files in the File menu and save again. The label shows the added size.

Open files from your file manager

On Linux, run scripts/install_desktop_integration.sh /absolute/path/to/faris-app from a source checkout. It works at user level. Add --uninstall to remove it. File managers do not show the file’s preview thumbnail.

The file itself

A .faris file is a zip container with a manifest and one content-addressed blob for each recorded file. The repository’s study file document describes the format, its size policy and its reading rules. Unknown fields are ignored, so later minor versions can add fields. An unknown major version is refused.

Next: Export a brief, tables and charts.

Export a brief, tables and charts

An export is a folder a colleague can read without FARIS. The .faris file stays the source of truth, and the export names its SHA-256 when the study has been saved.

Export from the desktop

Choose Export… in the top bar. The app asks for a folder and writes <study name>-export/ into it. It never writes into an existing export folder.

Export is unavailable while the histories, uncertainty ranges, sweep or saved evidence are still calculating or loading. Hover the button for the reason. It is also unavailable when the study has no operating assumptions.

What the folder holds

The PDF footer carries the version, the date and the study-file hash. For an unsaved study it reads “Unsaved study — no study file hash”.

Every PDF page, CSV, chart and the manifest carry the research-screening statement. Each CSV starts with a # comment line holding it. To skip that line when you load a table, use:

pandas.read_csv("data/histories.csv", comment="#")

Values are written at full precision, and units are in the CSV headers. Each kind column uses the labels in Reading the numbers.

Uncertainty in the export

With an ensemble for at least one arrangement, the export gains the third PDF page, a shaded P5 to P95 band on the magnet-fluence timeline, two charts of tritium and net electricity bands, and the three ensemble CSVs. An arrangement whose ensemble is not evaluated keeps its nominal values, labelled “no uncertainty range” with the reason. The next step is written as text beside it. Every range is labelled as transport Monte Carlo sampling uncertainty only.

Export from the command line

faris study-file export demo.faris --output /path/to/parent

The parent folder must exist. This writes the same <study name>-export folder without the desktop. It recalculates the histories and the sweep from the recorded assumptions and rates, as the app does on opening the file. It has two differences from the desktop:

• It has no 3D view. The PDF has no 3D image, and the manifest says so.
• It reuses only the ensembles stored in the file and never calculates new ones. An arrangement with none is exported as “not calculated”. Run the ensembles in the desktop, or with faris history ensemble, and save first.

Any failure exits non-zero with nothing written.

If the 3D view is missing

The export notes “The window capture did not arrive; this graphics backend may not support screenshots.” The rest of the export is written.

Next: Command line.

Command line

The package holds two programs: faris-app, the desktop, and faris, the command line. The faris command needs no graphics, Python, OpenMC or Avila Core, except for the commands marked below. Run faris --version to check the version and faris COMMAND --help for every flag of a command.

Errors exit with status 2. A study file that fails verification exits 1.

Commands

Work with study files

faris study-file create --bundle port/bundles/reference.transport-bundle.json \
  --control-bundle control/bundles/reference.transport-bundle.json \
  --sweep-bundle sweep/blanket-045cm.transport-bundle.json \
  --assumptions operating-assumptions.json \
  --evidence saved-study-port-reference.json [--pack-evidence] -o demo.faris
faris study-file inspect demo.faris
faris study-file verify demo.faris
faris study-file unpack demo.faris out/
faris study-file export demo.faris --output exports/

--bundle, --physics and --sweep-bundle are repeatable. --pack-evidence stores the Core evidence inside the file. --view records a view from a JSON file, --zstd-level sets the compression level (default 15), and --preview stores a PNG thumbnail. create never overwrites an existing file. See Study files.

Calculate a history

Operating histories and their uncertainty run headless from a recorded transport run:

faris history from-run --scenario <scenario.json> --run <run.json> \
  --assumptions scenarios/arc-inspired/demountable-magnet-assumptions.json \
  --output history.json --rates-output rates.json
faris history ensemble --assumptions scenarios/arc-inspired/demountable-magnet-assumptions.json \
  --rates rates.json --samples 200 --output ensemble.json

--samples is 1 to 2000 and defaults to 200. --seed and --threads are optional. An ensemble that is not evaluated is written and exits 0, so read its status. Uncertainty ensembles explains the result, and Method the calculation.

Desktop options

faris-app takes a .faris file as its argument. Options you may want:

Run faris-app --help for the rest.

Next: Run your own transport.

Run your own transport

You do not need this to explore the recorded study. Use it to run new fixed-source transport yourself, for example to record a case with your own seed or history count. It uses the same engine from the command line and from the desktop.

What you need

• OpenMC 0.15.3 in an environment you provide. The run refuses any other version.
• The nuclear data the study was audited against. The recorded runs use FENDL-3.2 neutron data and ENDF/B-VII.1 photon data. The photon data come from a local overlay that FARIS does not ship. Its acquisition is described in the repository’s photon library document.
• A library audit of your own installation. The audit file in the repository records one workstation’s cache. Run integrations/openmc/audit_library.py on yours and supply its output. FARIS does not silently accept differences in library content.

The data stay outside the repository. They are not part of the package.

Run a case

faris reactor run \
  --scenario scenarios/arc-inspired/cold-coupled-control.scenario.json \
  --physics scenarios/arc-inspired/cold-coupled-control.reference.physics.json \
  --mesh-preset outboard-local \
  --audit references/openmc-library-audit.json \
  --cross-sections /path/to/cross_sections.xml \
  --python /path/to/openmc-env/bin/python --openmc /path/to/openmc-env/bin/openmc \
  --particles 10000 --batches 100 --seed 123456789 --threads 1 \
  --output runs/cold-coupled-control-reference-001

The scenario and physics files shown are the port-free arrangement with the reference allocation. The port arrangements use cold-reference-port.scenario.json and its matching physics files.

The limits are:

• 30 to 1000 batches, and at most 50 million histories in all.
• At most 32 threads.
• A timeout of 3,600 seconds by default (--timeout-seconds), at most 14,400.
• --output must be a new directory. The command refuses an existing one.

--mesh-preset is coarse (the default), outboard-local-coarse, outboard-local or outboard-port-window. The recorded runs use the outboard-local mesh. Ctrl-C cancels the run and its solver processes. These limits bound resources. They are not a sandbox.

A run records the per-batch results behind the covariance that the uncertainty ensembles need. Small regions need many histories. At 10 million histories, the port-sector fast flux of a port-free control has a 36 to 54 % relative error. That is too poorly sampled for ensembles, which is why the recorded controls use 30 million. A 30 million history run took about 68 minutes at 7 threads on the reference laptop.

Check a run

faris reactor inspect \
  --scenario scenarios/arc-inspired/cold-coupled-control.scenario.json \
  --run runs/cold-coupled-control-reference-001/run.json

This rechecks the run’s recorded inputs, raw artifact, sampling, audit, adapter identity, volumes and normalization. Neither a completed process nor an accepted normalization is a scientific verdict. Scientific qualification stays not evaluated.

Replay or run in the desktop

faris-app \
  --scenario scenarios/arc-inspired/cold-coupled-control.scenario.json \
  --physics scenarios/arc-inspired/cold-coupled-control.reference.physics.json \
  --physics scenarios/arc-inspired/cold-coupled-control.breeder-emphasis.physics.json \
  --run runs/cold-coupled-control-reference-001/run.json --field-view flux-slice

Repeat --run for the other arrangement. Add --python, --openmc, --audit and --cross-sections to enable Run and review transport in the Simulate step, or set them under Transport configuration. Closing the app cancels its transport workers. Camera interaction stays available while a job runs.

A study started from --run records cannot be saved as a .faris file, because a study file holds recorded-transport bundles. faris transport pack packages a completed run into a portable bundle:

faris transport pack --run runs/cold-coupled-control-reference-001/run.json --output reference.transport-bundle.json

Where to read more

The repository documents the details: the cold-reference workflow covers the materials, the source, the recorded tallies and the verification steps, and the transport boundary covers the contracts, normalization and trust limits.

Next: Reading the numbers.

Reading the numbers

Every value in FARIS carries a badge that says what kind of number it is. Hover a badge to see why it applies and what would settle it.

Kind labels

The five you meet most are calculated, authored, literature, conditional and not evaluated. Transport results are calculated. Plant inputs, service limits, outage durations and efficiencies are authored or literature. Fuel, maintenance, replacements and electricity are conditional on them.

Not evaluated explains itself

FARIS never leaves a bare unknown. Every value that is not evaluated, and every missing range, says why it is not evaluated and what the next step is. Hover shows it. It is also written as text on the screen and in exports.

A transport result carries the label “cold-data surrogate · NOT_EVALUATED”. Scientific qualification is not evaluated, even for completed transport. Scope and limits says why.

Standard errors

Transport values appear as a mean with its Monte Carlo standard error, the sampling error of that one run. A smaller standard error means the run sampled that quantity better. It says nothing about whether the model is right.

The recorded runs have standard errors below 0.04 % for tritium production and heating. For the regional magnet fast flux they are 5 % to 24 %, and up to 30 % for the port-sector region of the port-free controls. Small regions are poorly sampled, which is why regional magnet results, and the replacement counts that follow from them, carry the most noise.

The 2σ flags

In Compare, each transport difference carries a flag. FARIS compares the difference with 2·√(SE₁² + SE₂²). “Beyond 2σ sampling noise” means the difference exceeds that. “Within 2σ sampling noise” means it does not. The runs use different seeds and their covariance is not modelled, so this is a screening flag, not a significance test. It says nothing about nuclear data, geometry or model form.

Ranges

Ensemble ranges are the median and the 5 to 95 per cent range (P5 to P95), with the share of samples for each event. They carry only the Monte Carlo sampling uncertainty of the transport. The true uncertainty is larger. See Uncertainty ensembles.

Service limits

Service limits, such as the magnet’s 3 × 10²² n/m² fast fluence, are screening values from the literature or authored. They are not material allowables. The limit compares with a regional average, not a local peak.

The research-screening statement

“Research screening only. These results are not a licensing, safety or design basis.” is in the bottom bar of every step, on every PDF page, as the first line of every CSV, on every saved chart and in the export manifest.

Next: Method.

Method

This chapter summarises what FARIS computes. The repository documents each part in full. It links to them at the end.

Transport

Each arrangement is a full-torus model of concentric layers, solved with OpenMC fixed-source Monte Carlo transport, with neutrons and photons coupled. The recorded runs use OpenMC 0.15.3, FENDL-3.2 neutron data and ENDF/B-VII.1 photon data.

The source is uniform in the plasma volume, isotropic and monoenergetic at 14.1 MeV. One source neutron stands for one D-T reaction of 17.6 MeV. At 525 MW that is about 1.86 × 10²⁰ source neutrons per second. OpenMC reports each score per source neutron with its standard error. FARIS then multiplies by the source rate and divides by volumes to get physical rates and densities.

The materials are authored cold-data surrogates: tungsten for the first wall, solid Li₂BeF₄ with 90 atom per cent lithium-6 for the blanket, titanium hydride for the shield, iron as a structural stand-in and copper as the magnet stand-in. Scope and limits says what that means for the results.

The responses are:

• Tritium production, in H3 atoms per source neutron.
• Heating, from coupled neutron and photon transport.
• Flux by component, with neutron and photon spectra.
• A 3D flux map on a mesh around the outboard side.
• Fast-neutron flux (neutron energy above 0.1 MeV) in three regions of the magnet: the inboard half, the outboard half outside the port sector, and the port sector, the 20° sector behind the port.

Covariance from batches

Each run records the per-batch value of every scalar response. FARIS takes the sample covariance of those batch values, divided by the number of batches, as the covariance between the response means. It first checks that the batch values reproduce OpenMC’s own means and standard errors. Correlated quantities, such as tritium production and heating, can then move together when sampled.

The operating history

The history is a deterministic ledger driven by one transport result. It is conditional on the authored operating assumptions and is not a prediction.

• Tritium. Opening stock, breeder production, D-T burn, imports, processing delay, process loss and radioactive decay go into one site balance. The balance is checked at every recorded state.
• Exposure. A component accumulates exposure only while the source operates: its flux times operating time. A service limit names a component, a response, a threshold and its source. When a replaceable component reaches a limit, a replacement outage starts and that component’s exposure resets. A permanent limit stops operation.
• Fuel. The source stops when usable tritium falls to a reserve and restarts at a higher threshold. This is a control rule, not a plant control system.
• Energy. Alpha heating and recovered transport heat go through an authored thermal-to-electric efficiency. Auxiliary load is subtracted, and net electricity is signed, so it can be negative.

Operate lists the assumptions you can change.

Ensembles

An ensemble draws the driving rates from a multivariate normal distribution with the recorded means and covariance, and runs the history once for each draw. Each sample has its own random stream derived from a seed, so results do not depend on the thread count. Draws with impossible rates are rejected, and if more than 1 per cent of accepted samples are rejected, the ensemble is not evaluated.

Each output is summarised by its median, its 5 to 95 per cent range, and distribution-free confidence intervals on those quantiles. Discrete outcomes get shares with Wilson intervals. A paired comparison subtracts sample i of one arrangement from sample i of another, which is valid only for independent transport runs. Uncertainty ensembles describes how to read them.

Controls

Independent Decimal-arithmetic checks cover the half-life decay, the source-rate conversion, the mass balance and the heat conversion, and numerical refinement checks cover the time step. They show the ledger arithmetic is repeatable. They do not bound transport statistics, nuclear data or model error.

Read the details

• Operating history: the ledger, its controls and the ensemble method.
• Transport boundary: normalization, regions and the covariance method.
• Cold-data reference: materials, source and recorded tallies.

Next: Scope and limits.

Scope and limits

FARIS 0.1.0 is research-screening software and a deliberately narrow demo. Its results are not a licensing, safety or design basis. Nothing in FARIS is a licence, safety, certification or validation claim.

FARIS is a design model of one study. It is not a model of a real machine.

What the demo is not

• Not the published ARC design. The geometry is idealised: concentric tori with one outboard port. The ARC paper is design precedent, not a specification.
• Not a plugged port. The outboard port is an open 0.30 m × 0.30 m duct with no shield plug. It is a bounding streaming case. In the port arrangements it drives the magnet replacements. With the demountable-magnet preset, the port-sector magnet limit is reached 0.65 years into operation and the magnets are replaced about 30 times in 30 years. Without the port, they are replaced at most once. A shield plug would reduce the streaming, and FARIS has not modelled one.
• Not a peak magnet fluence. The magnet check uses regional averages: inboard, outboard and port sector. A local peak needs variance reduction aimed at the magnet, which is planned for 0.2. A hot spot can reach a limit sooner than its region’s average does.
• No activation, decay heat or shutdown dose. Maintenance timing ignores them. They are planned for 0.2, and shutdown dose later. There are no physical degradation models.
• Linux only. The bundled programs are hash-pinned, not signed.

Transport inputs

Transport is a cold-data surrogate. The materials are authored recipes, not a design’s real materials. The first wall is tungsten, the blanket solid Li₂BeF₄ and the shield an ideal titanium hydride. Iron stands in for the structure and copper for the magnet. The data are at one nominal temperature, with no thermal-scattering data for the crystalline blanket and shield materials. Low-energy spectra and breeding are therefore not qualified.

The source is authored. The whole-model tritium response includes production anywhere in the model, so it is a gross rate and not a breeder-only breeding ratio. Heating is an OpenMC deposition score, not a thermal balance, and the history’s energy ledger is not a coolant or thermal-cycle calculation.

Scientific qualification is not evaluated, including for completed transport. A successful run is not a scientific verdict. The recorded campaign does not reproduce an experimental neutron-transport benchmark, and it has no design-level validation. A code-to-code comparison against an ITER 1D reference is unavailable without traceable reference responses.

Uncertainty

Only transport Monte Carlo sampling uncertainty is propagated. Nuclear-data, geometry, material and model uncertainty are not, so the true uncertainty is larger than the ranges shown. The tritium half-life and every authored assumption are not sampled either.

The recorded runs use 30 million histories for the port-free controls and 10 million for the port and sweep cases. Standard errors are below 0.04 % for tritium production and heating, and 5 % to 24 % for the regional magnet fast flux (up to 30 % for the port-sector region of the port-free controls).

Authored assumptions

Service limits, outage durations, recovery fractions, processing delays and plant efficiencies are authored or literature screening values. They are not material allowables or measured plant data. Fuel, maintenance, replacement events and electricity are conditional on them. The planned outages are illustrative and are not an availability estimate.

The magnet’s 3 × 10²² n/m² fast-fluence limit is a literature REBCO screening value (Sorbom et al. 2015). It is applied to the average of each region.

Local fields

Sparse local mesh estimates keep their unresolved sampling uncertainty. The port-window comparison is a declared mixed-volume spatial average, not a magnet peak.

Where the evidence stands

The repository tracks the evidence and the open work: the scientific baseline, the requirements and the demo roadmap. Keep the exact version with a study. Later changes do not rewrite what a recorded study holds.

Next: Troubleshooting.

Troubleshooting

The app will not start

The desktop needs a graphical session and compatible graphics drivers. Leave display-backend and DPI overrides unset in normal use, so a high-DPI desktop reports its native scale. The recorded frame rates were measured on both X11 and Wayland.

launch.sh needs python3 and enough free temporary space. If it stops before opening the app, read its message and check the amounts in the package’s README.md.

Messages when you open a study

“recorded case, mesh or response definitions differ from this FARIS build: …” The study was recorded by an earlier build. The full message continues: “The run was probably recorded by an earlier version; rerun the transport case with this build to use it.”

“Cannot open NAME: …” The file could not be opened. The reason follows. Reading is fail-closed. A file is refused if a blob does not match its recorded SHA-256 (“blob … does not match its recorded SHA-256”), if its size is wrong, if it uses an unsupported encoding, or if its version is not major version 1 (“unsupported study-file version …”). Run faris study-file verify FILE to see which part failed.

“Core receipts not included” The Core archives are referenced, not packed. See Study files. A listed archive that is “not found” is missing from beside the file. One whose SHA-256 differs from the record is not used.

Uncertainty and export

“No uncertainty range: …” The ensemble is not evaluated. The line gives the reason and the next step. Typical reasons are a transport record without covariance, or more than 1 per cent of draws rejected. See Uncertainty ensembles.

Export is unavailable. Hover the button. It says when histories are still calculating, or when the study has no operating assumptions.

The 3D view is missing from an export. The export notes “The window capture did not arrive; this graphics backend may not support screenshots.” The rest of the export is written.

A command-line export has no ensembles. It uses only the ensembles stored in the file. Run them in the desktop and save, or use faris history ensemble.

Operate and Evidence

Save is greyed out. Hover it for the reason. Nothing recorded can be saved when the study was started from --run records.

A badge says “receipts cover the loaded assumptions”. The saved Core receipts were executed with the loaded assumptions, and the current preset differs. Choose Use the covered assumptions.

Compile study says the Core executable is unavailable. Choose the installed Avila Core file under Compiler settings, or start the app with --core.

Still stuck

Report reproducible problems through GitHub issues. Include your version, the command or step, and the message.

Releases

FARIS follows semantic versioning from 0.1.0. Before 1.0, a minor version may change file formats or the command line. The changelog lists such changes under Changed, with what to do.

The full history is in the changelog. Releases are on the releases page.

0.1.0, 2026-10-05

The first public release, a deliberately narrow demo that is complete for one study: an ARC-inspired compact D-T tokamak, studied from 3D Monte Carlo transport through 30 years of operation, with the transport sampling uncertainty carried into every year.

• Study. A five-step workspace (Design, Simulate, Operate, Compare, Evidence) with a replayable first-run tour. Four recorded arrangements: two blanket/shield allocations, each with a finite outboard service port and a matched port-free control. A seven-point allocation sweep. A 30-year operating history that recalculates in about a second from sliders.
• Uncertainty. Covariance between all scalar transport responses from per-batch results. History ensembles of up to 2,000 histories, with a median, a 90 % range and event probabilities for every output. Ensembles fail closed when more than 1 % of draws are non-physical. A paired comparison of two arrangements’ ensembles.
• Magnets. Fast-neutron flux on the inboard half, the outboard half and the sector behind the port, each with its own service limit. The first limit reached triggers the replacement and is named in the event.
• Files and export. .faris study files checked by hash on every open. Export to a PDF brief, CSV tables and SVG and PNG charts, from the desktop and from faris study-file export.
• Evidence. Studies compile and run through Avila Core, which records hash-bound receipts.

The known limits of this release are in Scope and limits.

Next: Where FARIS is going.

Where FARIS is going

The next version, 0.2, builds on the same study:

• ARC-fitted geometry. Separate inboard, outboard and vertical thickness for every layer, using the published ARC radial build. It adds 18 discrete TF coils, a double-null divertor, several ports, and cross-section and radial-build views. FARIS can then be compared with the published ARC magnet lifetime (at least 9 full-power years to 3 × 10²² n/m²; Sorbom et al. 2015).
• Peak magnet fluence. Variance reduction aimed at the magnet (FW-CADIS weight windows), so the local peak is reported alongside the regional averages.
• Activation and decay heat at every outage, through ACTINV, with material impurities bounded three ways (none, specification maximum, per ppm). The uncertainty of the neutron spectrum is reported separately.

Further out, and not yet scheduled: CAD geometry (through Paramak and DAGMC), shutdown dose, and Windows and macOS builds. The plan and its decisions are in the demo roadmap.

Measurable goals for every part of FARIS are in the requirements.

Next: Avila Labs account (optional).

Avila Labs account (optional)

The desktop app has an optional Avila Labs account. Every part of FARIS works fully without one. FARIS has no feature that needs an account.

What you see

At the right end of the top bar there is a grid button that opens the Avila Labs tools, and a Sign in button. After you sign in, the button becomes an account chip. The first time you start the app, a prompt may offer to sign in. It does not appear while the tour plays, or in scripted runs.

Sign in

1. Choose Sign in. The sign-in card opens. Choose Start sign-in.
2. The card shows a short code and an Open browser button. Your browser opens and asks you to approve this device. Check that the page shows the same code.
3. Approve it in the browser. The card reads “Signed in as” followed by your account.

If you deny the sign-in, or the code expires before you approve it, the card says so and offers Try again. Close leaves the card without signing in.

The app identifies itself to the service as faris-desktop. Choose Sign out to leave the account. Signing out revokes the token on the service and deletes the local credentials file.

What is stored and sent

The token is saved in credentials.json (mode 0600), in the folder named by AVILA_CONFIG_DIR, or in ~/.config/avila when that is not set. The credentials file also keeps your email address for display.

The app sends the service a sign-in request with the app name, the token during sign-in, and afterwards the token to check your account status about once a minute. Nothing from your FARIS work is sent: no inputs, results or files. The account service’s privacy notice has the details.

The roadmap plans to move token storage into the operating system’s credential store where one exists, with an owner-only file as the fallback.