A Julia distribution that ships SciBmad — the Julia
toolkit for charged particle beam dynamics. Besides SciBmad, this distribution bundles a number of additional
packages and their dependencies.
A list of these additional packages is in the Project.toml file.
Install this distribution (see below), launch the Distribution executable, and using SciBmad returns
immediately: no package installation, no first-use compilation wait.
Additional packages can still be installed with Pkg without triggering recompilation of the bundled ones.
The distribution is built with AppBundler.jl and follows the Jumbo template. All packages in the distribution, including dependencies, is bundled into the stdlib path of the shipped Julia so that they are never accidentally recompiled.
- SciBmad core:
SciBmad,Beamlines,BeamTracking,NonlinearNormalForm,GTPSA,TPSAInterface,AtomicAndPhysicalConstants,FundamentalFrequencies,BatchSolve,KernelAbstractions - Differentiation and arrays:
ADTypes,DifferentiationInterface,ForwardDiff,ReverseDiff,FiniteDiff,StaticArrays,TypedTables,PreallocationTools - Optimization and solvers:
Optim,NLSolversBase,OptimizationOptimJL,OptimizationLBFGSB,NonlinearSolve,Metaheuristics,Sobol,QuasiMonteCarlo - Statistics:
Distributions,Turing - Plotting:
Makiewith theCairoMakie,GLMakieandWGLMakiebackends, plusPlotsandLaTeXStrings - Data and utilities:
DataFrames,Graphs,JSON,SpecialFunctions,ReferenceFrameRotations - Interactive tooling:
Infiltrator(loaded automatically bymeta/startup.jlin interactive sessions) - Notebooks:
IJulia, so the bundled Julia can be used as a Jupyter kernel (see "Setting up the Distribution for use from Jupyter" below) - Python interoperability:
PythonCall, together with thePython_jllinterpreter it runs against
There are two ways to install: from conda, or from an app installer. Conda is the easier one and is recommended. The app installer route is documented at the very end of this README file.
Note that the distribution ships its own Julia, so Julia does not need to be installed separately. The bundled Julia is version 1.12.
To install and run SciBmad in a julia session do:
conda install -c bmad-sim scibmad # Only need to do once.
scibmad # Starts julia
using SciBmad # Brings SciBmad into scopeThe install may take a minute or two. Also the using SciBmad command may take a minute the first time.
This works on Linux (x86-64 and aarch64), macOS (Intel and Apple silicon), and Windows (x86-64). Mamba, micromamba and pixi work as well as conda.
On Windows, the install can fail when a file's full path would be longer than
Windows allows, which by default is 259 characters. conda then reports InvalidArchiveError
with No such file or directory, or CondaVerificationError saying the package "appears
to be corrupted". The distribution is built to fit with any user name and conda's usual
install folders, but an older release, or conda installed in an unusually deep folder,
can still hit the limit. To fix it, enable long paths, once per machine. In a PowerShell
window opened with "Run as administrator":
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name LongPathsEnabled -Value 1 -PropertyType DWORD -ForceThen delete the half-unpacked package, or conda will keep reporting it as corrupted. It is the folder named in the error, for example:
rmdir /s /q C:\Users\<user>\miniforge3\pkgs\scibmad-0.6.0+26.10.14-h9490d1a_0Then open a new terminal and run the install again.
Useful Conda commands:
conda list | grep scibmad # Installed version, e.g. 0.5.2+26.09.01 -- see "Version numbers" below.
conda search -c bmad-sim scibmad # List all versions available on the channel.
conda update -c bmad-sim scibmad # Update to the latest version.
conda uninstall scibmad # Uninstall. No channel needed: it only removes what is installed.A conda version looks like 0.5.2+26.09.01. The first part is the version of SciBmad
itself; the part after the + is the date the distribution was built, as YY.MM.DD with
month and day zero-padded. So 0.5.2+26.09.01 is SciBmad 0.5.2, built on 1 September 2026.
-
If installed with conda, run
scibmad. This starts Julia in the terminal. -
If installed from an installer, run the
SciBmadDistributionapp. This should open a Julia window. -
In Julia, the command
using SciBmadwill load the Distribution.
The Distribution bundles SciBmad, associated packages, and Julia itself into one binary executable.
When you startup Julia with the command scibmad, you are running the Distribution binary.
If you startup Julia with the command julia, you are running the standard Julia binary.
It is important not to confuse the two. When you are in Julia, you can see which binary is being used
using the command Sys.BINDIR. The result when running standard Julia is something like:
julia> Sys.BINDIR
"/Users/dcs32/.julia/juliaup/julia-1.12.7+0.aarch64.apple.darwin14/Julia-1.12.app/Contents/Resources/julia/bin"When using the Distribution executable, the result is something like:
julia> Sys.BINDIR
"/Users/dcs32/miniconda3/libexec/scibmad/bin"On Windows the Distribution is in a shorter folder, so the result is something like
C:\Users\dcs32\miniforge3\sb\bin.
Packages the user installs with Pkg go in a per-user directory outside the conda
environment (~/.local/share/scibmad, or %LOCALAPPDATA%\scibmad on Windows), so they
survive removing and recreating the environment. Set USER_DATA before launching to put
them somewhere else.
versions() prints the bundled packages and their versions:
julia> versions()
ADTypes 1.24.0
AtomicAndPhysicalConstants 0.11.5
BeamTracking 0.8.1
Beamlines 0.10.3
...
SciBmad 0.5.2Note: versions is only defined when using the Distribution executable.
versions("makie") filters by name, and versions(all = true) adds every dependency as
well, several hundred of them. It returns the name => version pairs it printed, so the
result can be used programmatically.
Note that Pkg.status() does not answer this question. The bundled packages live in
their own project, so what it reports is your own project, which on a fresh install is
empty. Use versions() instead. And make sure you are running the distribution's Julia --
scibmad, or the app -- rather than another Julia you have installed, which knows nothing
about any of this.
IJulia is bundled, so the Distribution can serve as a Jupyter kernel. Jupyter itself is not
bundled — use whichever Jupyter installation you already have.
If Jupyter is not yet installed, install with the command:
conda install -c conda-forge jupyterlab # or: pip install jupyterlabRegistering the kernel with installkernel is required.
To register the Distribution kernel do the following after running the scibmad binary
(and not the standard julia binary!):
using IJulia
installkernel("SciBmad Distribution"; # Register the SciBmad-Distribution kernel
specname = "scibmad-distribution",
displayname = "SciBmad Distribution")This registration only needs to be done once and only needs to be redone if the registration is deleted or a different Conda environment is used.
The installkernel function writes a kernel specification into the Jupyter data directory
and not inside the Distribution itself. With this, SciBmad Distribution appears in Jupyter's
kernel list and using this kernel with a notebook eliminates any precompilation wait.
Which kernel a notebook is using is shown in the top right of the notebook window, and can
be changed from the Kernel menu. To see what kernels are registered, run this in a Unix
command line:
jupyter kernelspec list | grep -B 1 -A 3 resource_dirThis prints a list of registered kernels and the associated paths to the kernels.
The kernel registered above runs Julia with a single thread. To get a multithreaded kernel,
pass Julia's --threads option to installkernel. As before, run this from the scibmad
binary:
using IJulia
installkernel("SciBmad Distribution", "--threads=auto"; # One thread per CPU core
specname = "scibmad-distribution-threads",
displayname = "SciBmad Distribution (threads)")Instead of auto, a fixed thread count can be given, for example "--threads=4". Using a
different specname from the single threaded kernel registers this as a second kernel, so
both appear in Jupyter's kernel list. Reusing specname = "scibmad-distribution" instead
replaces the single threaded kernel. To check the thread count, run Threads.nthreads() in
a notebook using the kernel.
Since the Distribution kernel is registered directly with Jupyter,
Jupyter can be started from either the standard Julia executable (using the julia command)
or the Distribution executable (using the scibmad command) with:
using IJulia
notebook() # Starts Jupyter server in browser or can use...
jupyterlab() # the more modern interface.Starting Jupyter this way still does not choose a kernel for you. Pick
SciBmad Distribution from the kernel list once the notebook opens, or the notebook runs
whatever kernel it defaults to.
-
If desired, modify the set of packages to be bundled by editing
Project.toml. -
Edit
Project.toml: set theSciBmadcompat entry to the version to build the distribution around. Also update theversionstring to the current date. The format is"YY.M.D"whereMis the month andDis the day without any leading zeros. Example: Use"26.8.3"instead of"26.08.03".If changing the Julia version, this needs to be changed in three files:
Project.toml,meta/Project.toml, and.github/workflows/Release.yml -
Re-resolve the package set so that
Manifest.tomlmatches the new compat entry;julia --project=. -e 'using Pkg; Pkg.update()' -
Install the build dependencies. This also re-resolves
meta/Manifest.tomlagainst the Julia version set inmeta/Project.toml, so it is required even if you skip the local build below:julia --project=meta -e 'using Pkg; Pkg.instantiate()' -
Optionally, verify the build locally. This is not needed to produce a release but can save time when debugging. The output goes to the gitignored
builddirectory, and the release workflow rebuilds everything from a fresh checkout. It may be worth doing to catch a broken build in one local run rather than after a five-platform CI matrix, but it targets the host platform only, so it cannot reproduce the platform-specific failures the workflow guards against:julia --project=meta -m AppBundler build . --build-dir=build --selfsign -
Push the updated
Project.toml,Manifest.toml,meta/Project.tomlandmeta/Manifest.tomlto the GitHub repo main branch via a Pull Request.meta/Manifest.tomlrecords the Julia version the build dependencies were resolved against, and the release workflow installs exactly the versions it pins. -
Delete the previous release from anaconda.org before publishing a new one. The channel's storage quota is about 10 GiB and a release is about 5 GiB, so only two fit. A push to Anaconda.org that that would lift the storage over the limit fails with
402 Payment Requiredafter every platform has built, and leaves a version on the channel with no files under it. See Issue #32. -
In GitHub under the
Actionsmenu, pressBuild Release Assetsand thenRun workflow. To have the bundles attached to a release, put the tag of an existing release in the optionalRelease tag to upload tofield; left empty, the run only leaves the bundles as workflow artifacts, which are deleted after a day. The same workflow also runs automatically whenever a release is created.
The conda package is built and published by a separate workflow from the installers, in
.github/workflows/Conda.yml, from the recipe and staging driver under meta/conda/. It
publishes to the bmad-sim channel on anaconda.org.
To publish a release: in GitHub under Actions, press Build and Publish Conda Packages,
then Run workflow, and tick publish. Left unticked, the run builds and tests every
platform and leaves the packages as workflow artifacts, which is the way to check a change
without putting anything on the channel. The same workflow runs automatically when a
release is created. Two other inputs are useful:
platformstakes a comma-separated list instead ofall, so one target can be rebuilt without waiting on the other four -- each job spends over an hour precompiling. The names aremacos-x86_64,macos-aarch64,linux-x86_64,linux-aarch64andwindows-x86_64, not the conda subdir names.artifacts_from_runtakes the ID of an earlier run and publishes the packages that run produced, skipping the builds entirely. This is for when the packages are fine and only the upload failed; it turns a three-hour retry into a two-minute one.
Some things about this are not obvious from the files:
-
meta/conda/stage.jlcallsAppBundler'sJuliaImg.stagedirectly rather than going throughAppBundler.main. The DMG, MSIX and Snap paths each wrap the same payload in a differently shaped container, whilestageis the step underneath all of them, so calling it gives one layout on every platform and skips code signing -- which a conda package neither needs nor wants, since an absent signature is nothing for Gatekeeper to reject. -
The payload is staged with
RUNTIME_MODE=MIN, not theSANDBOXthe installers use. SANDBOX hasAppEnvlocate the per-user depot through the container it assumes it is running in, and a conda install is in no container: outside one, the Snap and MSIX code paths both fall back to a temporary directory, and anything the user installed withPkgwould be gone by the next session. MIN readsUSER_DATAfrom the environment on every platform, and thebin/scibmadlauncher points it at a persistent per-user path outside the prefix. -
Symlinks are resolved into copies on Windows only. The payload carries around 500 relative symlinks from Julia package sources, and they cannot survive the copy into the prefix there. They also need a privilege to create that a user installing the package may not have.
-
Windows paths are kept short in two ways. Without long paths enabled, Windows refuses any path over 259 characters. conda unpacks the package into
C:\Users\<user>\<conda root>\pkgs\scibmad-<version>-<hash>_0\before linking it into the environment, and that uses about 60 to 80 of them before the payload starts.First,
build.batinstalls the payload into%PREFIX%\sbrather than thelibexec\scibmadused on macOS and Linux, which saves 13 characters.Second, the Windows payload is pruned (
prune_for_windows!instage.jl). Unpruned, Qt's private headers reached 199 characters inside the payload. Two kinds of file are removed:- in artifacts:
include/,lib/cmake/and Qt'sobjects-*directories - in package sources:
test/,docs/andbenchmark(s)/
Two directories are removed from every platform's payload, not only Windows (
prune_unused!):- NonlinearNormalForm's
fpp-ptc-sandbox/. It holds Fortran experiments, along with CMake build output that the released package commits: about 600 files and 16 MB, none of which the package loads. - Qt's
qml/modules in the Qt6Declarative artifact, about 1,600 files and 24 MB. They are read only by a QML engine, and nothing in the distribution starts one. GR's Qt viewergksqtis a QtWidgets program.
Nothing a precompile cache header lists is deleted, because a missing source file would make Julia recompile that package. Staging then fails if any path is still longer than
WINDOWS_MAX_RELPATH(165). The GitHub runners have long paths enabled and short workspace paths, so without this check CI would never see the problem. After pruning, the longest path is a DifferentiationInterface extension source, at 160 characters. The precompile caches depend on it, so it stays. With that andsb, the install fits for any user name of up to 22 characters, even with conda underAppData\Local; Windows user names have at most 20. Only a conda root deeper than usual should need long paths enabled. - in artifacts:
-
Every matrix entry names its conda subdir explicitly. rattler-build otherwise infers it from the machine it is running on, which is wrong for the macOS targets because both are cross-built on an arm64 runner -- an x86_64 payload would be published as
osx-arm64, and installed on machines that cannot run it. -
The upload deliberately does not pass
--force, so republishing a version that is already on the channel fails rather than silently replacing what people have installed. Bump the version instead, or remove the old files on anaconda.org first. -
Publishing needs an
ANACONDA_API_TOKENrepository secret holding a token created from inside thebmad-simorganization on anaconda.org, with "Allow write access to the API site" enabled. A token made from a personal account has no rights in the organization's namespace and fails with a 401 that reads like a missing secret. The workflow passes it to rattler-build asANACONDA_API_KEY, which is the name rattler-build reads.
Files under meta/patches/<Package>/… are copied over the corresponding files of the bundled
packages during the build. Five patches are currently applied:
-
meta/patches/GLMakie/src/precompiles.jl— GLMakie's@setup_workloadblock opens an OpenGL screen, which is not available while packages are precompiled into the bundle. The patched copy comments that block out and keeps the staticprecompile()statements. It was generated from GLMakie v0.13.13 and must be regenerated when GLMakie is upgraded: copysrc/precompiles.jlfrom the new version and comment out themacro compiledefinition and thelet @setup_workload … endblock. -
meta/patches/PythonCall/src/Core/juliacall.jl— PythonCall locates its bundledjuliacallPython package throughROOT_DIR, which isdirname(dirname(@__DIR__))and is therefore frozen at precompile time. AppBundler precompiles into a staging directory and the bundle is installed somewhere else, so the recorded path no longer exists andusing PythonCallfails withModuleNotFoundError: No module named 'juliacall'. The patched copy locates the package through the load path instead, which follows the bundle wherever it is installed. It was generated from PythonCall v0.9.35 and must be regenerated when PythonCall is upgraded: copysrc/Core/juliacall.jlfrom the new version and replace the two uses ofROOT_DIRinsideinit_juliacallwith the load-path lookup. -
meta/patches/PythonCall/src/C/C.jl— PythonCall asks CondaPkg to download and resolve a Python environment when it is first loaded. The bundle ships its own interpreter inPython_jll, and CondaPkg cannot work inside a read-only install anyway, so the patched copy points PythonCall at the bundled interpreter fromPythonCall.C.__init__. It runs there, rather than frommeta/startup.jl, because the build needs the same configuration: compiling a package that has a PythonCall extension loads PythonCall in a Pkg worker process, which never reads a startup file. The JLL is loaded on every such entry even when the environment variables are already set — Pkg's workers inherit environment variables but not loaded libraries, and Python'sctypes(imported byjuliacallduring initialisation) only findslibffibecause loading the JLL brought it into the process.The same patch skips the bundled interpreter on macOS x86_64, where Python_jll's build is unusable. It is compiled with a 10.10 deployment target, so clang guards the 10.12-only
getentropycall inpyurandomwith__builtin_available, which compiles to a call to___isPlatformVersionAtLeast. That symbol is left as a flat-namespace dynamic lookup and nothing in the process resolves it, so it binds to NULL andPy_InitializeFromConfigjumps to address zero.python3 -Vsurvives because it returns before reaching that code; anything else dies withSIGSEGV. The aarch64 build targets macOS 11, wheregetentropyneeds no guard, which is why only this one platform is affected. This is an upstream bug inPython_jll 3.11.12+0, and the skip can be dropped once a fixed build exists.On those two platforms the same patch also has to find libpython. PythonCall locates it by running
src/C/find_libpython.py, at a path@__DIR__baked in at precompile time — inside the build machine's staging directory, which does not exist on the installed machine. This is the same relocation problem thejuliacall.jlpatch solves forROOT_DIR. The patch runs the script from where PythonCall actually is and passes the answer inJULIA_PYTHONCALL_LIB.It was generated from PythonCall v0.9.35 and must be regenerated when PythonCall is upgraded: copy
src/C/C.jlfrom the new version and re-apply the block after theincludes along with the two calls in__init__. -
meta/patches/IJulia/deps/deps.jl— IJulia refuses to load unlessdeps/deps.jlexists:src/IJulia.jlaborts withIJulia not properly installed. Please run Pkg.build("IJulia"). That file is written byPkg.build("IJulia"), and AppBundler copies pristine package trees into the bundle without ever runningdeps/build.jl, so bundling IJulia used to fail every build — which is why it was dropped from the distribution in August 2026.Unlike the patches above, this one supplies the generated file rather than a forked copy of a source file, so it does not have to be regenerated when IJulia is upgraded; it only has to keep defining the two names
deps.jlis contracted to define.JUPYTERis set to the bare string"jupyter", whichfind_jupyter_subcommandalready treats as "look it up onPATH". That is deliberate: the stockdeps/build.jlrecords an absolute path to the Jupyter it found on the build machine, which is meaningless on the installed machine, and the bare string is what turns the lookup into a run-time one.IJULIA_DEBUGisfalse, which is what a stock build writes when the variable is unset, and as upstream it is frozen at build time. -
meta/patches/Conda/deps/deps.jl—Condaarrives as a dependency of IJulia and fails the same way, withConda is not properly configured. Run Pkg.build("Conda"). It is precompiled into the bundle whether or not anything calls it, so it needs the same treatment. The patch suppliesdeps/build.jl's own default values, computed rather than hardcoded so the build machine's depot path does not appear in the file.The
mkpathin it is load bearing:src/Conda.jlevaluatesconst PREFIX = prefix(ROOTENV)at precompile time andprefixthrows unless that directory already exists, whichPkg.build("Conda")would otherwise have created.One limitation is worth recording.
Conda.ROOTENVand everything derived from it stayconst, so they are still frozen at precompile time and inside the installed bundle they point at the build's staging depot, which no longer exists. Nothing in the distribution calls Conda — the only path that reaches it isIJulia.notebook()readingConda.SCRIPTDIRas a fallback afterSys.which("jupyter")has already failed — so this is latent rather than a fault. Making it correct would mean converting roughly tenconsts inConda.jlinto run-time globals, which is a fork of the file rather than a patch to it.
PythonCall is bundled with a Python interpreter, so using PythonCall returns in about a
second and needs neither a download nor a network connection. A patch to PythonCall itself
(see "Patches" above) points it at the Python_jll interpreter inside the bundle and switches
CondaPkg's environment management off; left to itself, PythonCall would try to resolve a Conda
environment on first use, which would both impose the wait this distribution exists to avoid
and fail outright, since it would have to write inside the read-only install directory.
Packages can still be added to that interpreter from within the distribution with CondaPkg
once it is pointed at a writable environment.
Two platforms get no bundled interpreter. Python_jll has no Windows build at all, and its
macOS x86_64 build is broken — it segfaults during interpreter startup on every Intel Mac,
not just under Rosetta (the patch documents the cause). There PythonCall falls back to
CondaPkg, which meta/startup.jl points at a writable directory beside the user's data and
tells which interpreter to install; the patch to PythonCall then finds the resulting library.
The first using PythonCall downloads a Python environment once and works normally
thereafter, though every later load still pays for a CondaPkg resolve check rather than the
bundled path's second or so. This is the slow path the distribution exists to avoid, and it is
taken only where the fast one is unavailable.
Three Makie backends are bundled. CairoMakie is the default used by the tutorial notebooks:
it renders static PNG/SVG/PDF output and needs no graphics hardware. GLMakie adds
interactive, zoomable, 3D-capable windows, but requires a working OpenGL 3.3 context, so
using GLMakie will fail on headless machines, over an SSH session without display
forwarding, and in some containers and virtual machines — use CairoMakie there. WGLMakie
renders into a browser and is the backend to use from a notebook served over the network. When
several are loaded, whichever was activated last (CairoMakie.activate!() and friends)
receives the plots.
For the macOS install, the closing chmod makes the installed bundle read-only.
The distribution ships its Julia
package cache inside the app itself; if Julia writes there while running, it invalidates the
app's code signature and macOS then refuses to launch it.
For the macOS install,
if you prefer the Finder, the order matters: click the app on the mounted disk image
first and approve it under Settings -> Privacy & Security, and only then drag it into
Applications. Dragging before approving is what fails. Then apply the chmod command
above to prevent modification of the app.
If the app shows a white "no entry" circle and will not start,
something has written a file inside the app bundle after installation, which invalidates its
code signature. macOS then refuses to launch it and reports nothing at all: no error dialog,
no crash report, no log entry. Confirm with:
codesign --verify --strict /Applications/SciBmadDistribution.appA reply of a sealed resource is missing or invalid identifies this problem, and the
accompanying file added: line names the file responsible. Removing that file restores the
signature and the app starts normally:
sudo rm "/Applications/SciBmadDistribution.app/<path from the file added: line>"Reinstalling also works, but the problem will recur unless the chmod -R a-w step from the
installation instructions is applied.
Conda is recommended because the app installers below are signed with a self-signed certificate, which both Windows and macOS refuse to trust without the manual steps described there. A conda package carries no signature for them to reject.
The app installation installs an app into the standard area. Startup means running the app
instead of using the scibmad command from the terminal with a Conda install.
Download the appropriate pre-built distribution (MSIX, Snap, or DMG) from the Assets section on the releases page (you may need to expand the Assets dropdown for prerelease versions), then follow the instructions for your platform:
-
MSIX (Windows): The released bundles are signed with a self-signed certificate, so Windows will not trust them out of the box. Open the MSIX bundle properties and add its certificate to the trusted certificate authorities first (see https://www.advancedinstaller.com/install-test-certificate-from-msix.html). Then double-click the installer and install the app.
-
Snap (Linux):
snap install --classic --dangerous SciBmadDistribution.snap -
DMG (macOS): The released bundles are signed with a self-signed certificate, so macOS does not trust them out of the box. In addition, macOS attaches a quarantine flag to anything copied out of a downloaded disk image, and Gatekeeper refuses to launch a quarantined app that it cannot verify. To get around the security, install from the Terminal, substituting the appropriate directory and name of the dmg file you downloaded in the second line (the other lines do not need to be modified):
sudo rm -rf /Applications/SciBmadDistribution.app hdiutil attach ~/Downloads/scibmaddistribution-26.8.26-aarch64.dmg ditto "/Volumes/SciBmadDistribution Installer/SciBmadDistribution.app" /Applications/SciBmadDistribution.app hdiutil detach "/Volumes/SciBmadDistribution Installer" sudo xattr -dr com.apple.quarantine /Applications/SciBmadDistribution.app sudo chmod -R a-w /Applications/SciBmadDistribution.app
This may take a minute or two. Note: The
sudocommands will ask for a password.The first line matters when upgrading and is harmless on a first install.
dittocopies into an existing directory rather than replacing it, so any file the old version had and the new one does not survives inside the new bundle. A file that is not in the app's signature is exactly what breaks it: the app then fails to launch with no error at all, in the way described under "Notes" below. Upgrading from a version that bundled a package the new one drops —Revisewas removed after 26.8.23 — hits this. Deleting the old app first avoids it.