Troubleshooting

Troubleshooting

Windows

"Windows protected your PC" on first run. This is expected: the build is not code-signed, as a signing certificate is a recurring cost not yet justified for a free tool. Click More info → Run anyway. Signing establishes who published a file, not that the file is safe; the published SHA-256 fingerprint provides the same integrity guarantee, so please verify that instead.

Antivirus flags the download. This can happen. PyInstaller single-file executables unpack themselves at runtime, which structurally resembles a packed dropper, and a newly published file has no reputation yet. UPX compression is disabled and full version information is embedded to minimise this. Verify the SHA-256, then report the detection to your vendor as a false positive; it also helps to mention in an issue which scanner flagged it.

The icon looks generic in Explorer. This is the Windows icon cache rather than the build; the icon is embedded at seven sizes. Run ie4uinit.exe -show, or copy the file to a new name to confirm. A fresh download never shows this.

Both platforms

"This app is open in N tabs." Information, not a fault. Opening the address again by hand gives you another view of the same server: the tabs keep their own inputs and results, but they share one solve queue, and closing every one of them shuts the application down after about 20 seconds. A tab left in the background keeps the application alive: browsers throttle hidden tabs to about one timer a minute, and the server waits 15 minutes (BT_CLIENT_TIMEOUT, seconds) before treating a silent tab as gone. Launching the executable a second time does not start a second copy; it opens a tab against the running one.

"The application backend has stopped - restart it and reload this tab". The page is still open but the process behind it is not running, so the run was never sent. Your inputs are still on screen: save the case, start the Breakthrough Simulator again, and reload the tab.

The browser opens but the page is unstyled black text. The bundled assets did not unpack. Re-download and verify the checksum.

It will not start at all. Read the log. It is written to logs/app.log:

Build	Log location
Windows	next to the .exe, falling back to %LOCALAPPDATA%\BreakthroughSimulator\logs
Linux	in the extracted folder, beside run-breakthrough-simulator.sh, falling back to ~/.local/state/BreakthroughSimulator

The first line of every run records the exact environment — Python, NumPy, SciPy, scikit-sundae, BLAS and the thread limits — and each solve appends its CVODE statistics. Include those lines when reporting a problem. The same text is visible in the app under Advanced Logs.

"N solves are already running or queued (limit 6)." Expected, and a guard rather than a fault. The app runs 2 solves at once and lets 4 more wait; anything beyond that is refused immediately instead of queueing without limit. A request that waits more than 15 minutes for a slot is also given up on. Close a tab you are not using, or wait for a run to finish. Each browser tab can start its own solve, so the quickest way to reach the limit is to leave several tabs open and press Run in each.

"Component 1 uses the TOTH isotherm, which the Competitive (extended Langmuir) mode cannot solve." Competitive mode is an extended-Langmuir mixture rule, so it is defined only for the SSL and DSL isotherms. Everything else — Toth, Sips, BET, Freundlich and the rest — needs IAST, which computes the mixture from the pure-component isotherms without assuming a Langmuir form. Presets carrying such a model (Activated Carbon is Toth/Toth) switch the app to IAST for you and say so; if you change the model by hand the pre-flight check refuses the run and names the two ways out.

A run took many minutes or stopped early. Solver robustness on demanding cases was substantially improved in 2026.09v4; please update to the latest release.

The breakthrough is a vertical line against the left-hand axis. The run is correct; the simulated time window is simply too long. A weakly adsorbing bed saturates far sooner than a strong one: Activated Carbon at 0.24 bar CO₂ reaches equilibrium breakthrough in about 30 s against Zeolite 13X's 150 s, so the 12000 s default squeezes the whole front into the first fraction of a percent of the axis. The suggestion under $t_{run}$ gives the range worth using, and now also warns when the value is more than 100× the equilibrium breakthrough time.

"This run was finished by the FALLBACK solver." Not a fault; read the mass balance before using the result. Every run starts on SUNDIALS CVODE, the only one of the three integrators that enforces the non-negativity constraints and the one every validated case was produced with. If CVODE does not converge, the same right-hand side is passed to SciPy LSODA, then SciPy BDF. LSODA goes first because BDF cannot clear the inlet pressure transient at $t=0$ on this system. The fallbacks are unconstrained, so a state may dip slightly negative where CVODE would have rejected the step.

Each fallback chooses its own steps and reports at them; nothing is interpolated afterwards. On the default Zeolite 13X case the fallback reproduces CVODE to 0.005 % of the feed mole fraction and 0.004 K, with the mass-balance error moving from 0.2129 % to 0.2138 %. Across adsorption and desorption, both presets and N_grid 30 and 60, the worst disagreement is 0.009 % of feed and 0.007 K. The test suite re-checks these on every build. The integrator used is named in Computed params, the exported report, and the log ([run_case] solver -- used=...).

BT_SOLVER=cvode disables the fallback, BT_SOLVER=scipy skips CVODE, and BT_FALLBACK_BUDGET (default 420 s) caps the total time the fallbacks may take.

A solve fails with "Solve failed: Every available solver failed on this case". All three integrators refused it. The response carries the full run configuration — isotherm models and basis, heat-of-adsorption mode, mass-transfer mode, momentum equation, gas pair, feed condition — and the same line is written to the log as [simulate] config --. Quote it when reporting the problem; the preset name alone does not identify a run, because the page sends every field individually. What to try, in this order: shorten t_run; check that the isotherm parameters suit the temperature and pressure you are running at, since a set fitted far from those conditions can put the bed somewhere the model cannot follow.

A solve stops with "Solve did not finish within 900s". The wall-clock limit per solve. Shorten t_run, which sets how much is simulated. A run that reaches the limit is usually stiff rather than long — the log's njev count rising against nfev is the sign — and the stiffness comes from the physics of the case.

The time column in my data file is not in seconds. It does not have to be. State the unit in the header (time [min], t_hours, t_ms) and it is converted. hh:mm:ss durations, 90 min, 1h 30m, and wall-clock timestamps (ISO or Excel dates, converted to seconds elapsed from the first row) are all read directly. With a bare time header and plain numbers the app assumes seconds, and warns if the span looks far shorter or longer than your t_run — the usual sign of a file in minutes.

Port 8000 is already in use. The app handles this itself. It probes the busy port: if the occupant is another copy of this application it opens that one instead of starting a second, and if it is any other program it steps to 8001, 8002, and so on, up to ten ports. The address it used is printed at startup and written to the log. BT_PORT and BT_PORT_TRIES move the search. A closed copy holds its port for up to 30 s after the last tab closes: 20 s of grace in case the tab was only reloading, then shutdown with a 10 s hard limit (BT_EXIT_GRACE, BT_SHUTDOWN_LIMIT).

Linux

./run-breakthrough-simulator.sh: Permission denied. The executable bit was lost — usually by copying through Windows, a zip tool or a network share. bash run-breakthrough-simulator.sh works regardless, or restore it: chmod +x run-breakthrough-simulator.sh install.sh BreakthroughSimulator/BreakthroughSimulator.

bad interpreter: /usr/bin/env bash^M. Windows line endings in the script, not a missing interpreter. sed -i 's/\r$//' run-breakthrough-simulator.sh.

GLIBC_2.XX not found. The build is compiled against the glibc of its build distribution. A newer distribution runs it; an older one cannot. The release notes state which distribution each build came from.

Nothing happens, or the binary is not found. The download is a folder, not a single file. The launcher needs BreakthroughSimulator/_internal/ beside it, so extract the whole archive and keep the layout intact. Running the inner binary directly also works.

The application-menu entry does nothing. install.sh writes absolute paths into the menu entry, so the entry breaks if the folder moves or was in a temporary location. Re-run ./install.sh from the folder's current location. It refuses /tmp outright — use ./install.sh --copy-to "$HOME/Applications" to relocate first. Remove an old entry with ./install.sh --uninstall, or --uninstall --purge to delete the folder and logs too.

Upgrading from an earlier version. Close the app, extract the new tarball and run its install.sh, with the same --copy-to destination if you used one. The previous installation — located through the menu entry, or already at the destination — is removed after a prompt (--yes skips it), so no files from the old version are left behind. Run logs are kept. A folder at the destination that is not an installation is never deleted; install.sh stops and says so.

The server starts but no browser opens. The app looks for $BROWSER, then xdg-open, gio, gnome-open, kde-open, x-www-browser, and the common browsers by name. Install xdg-utils or set $BROWSER if none is present. Either way, open the address printed at startup yourself — http://127.0.0.1:8000 unless that port was taken. The [browser] lines in the log say which opener was tried and how it failed.

Verifying your download

Every release ships a SHA256SUMS file. Check the file you received against it before running:

certutil -hashfile BreakthroughSimulator-windows.exe SHA256      Windows
sha256sum -c SHA256SUMS                                          Linux

Compare the result with the line for your file in SHA256SUMS. They must match exactly. If they do not, the file is not the one that was published — delete it.

Each release also ships requirements-lock.txt, the exact library versions that build was compiled from.