Installation
The simplebuild system and dgcode itself is supported only on unix systems (macOS and Linux), although it most likely will also work on Windows under the WSL (Windows Subsystem for Linux) with a virtual Ubuntu installation. It is used exclusively by entering shell commands in a terminal interface, so be sure you are familiar with such command line interfaces.
Install via conda
Current status: 
The recommended and easiest way to install dgcode is by creating an appropriate
conda environment based on the conda-forge
channel, in which all the dependencies are included. Which exact dependencies to
include, depends on the use-case but must always include at least the
simple-build-dgcode and compilers packages. For most users, the
recommended conda environment .yml file to use to create the environment is
the following:
name: dgcode
channels:
- nodefaults
- conda-forge
dependencies:
- compilers
- bash
- simple-build-dgcode >= 1.3.0
- ncrystal
- mcpl
- matplotlib
- zlib
- geant4>=11.1.3,<11.2.0
- geant4-data-ndl=4.7.0
- expat
- openscenegraph
- scipy
- hdf5
- pysimplegui<5 #v5 is no longer open source
- pip
You can download the above recipe file here: conda_dgcode.yml.
To use it, you must first install conda. Instructions for how to do that is beyond the scope of the present documentation, but in general this can be done in a variety of ways (installing Miniforge, Miniconda, Anaconda, or even via Homebrew). If you don’t have conda installed already and do not have any other reason for a preference, we would recommend to use Miniforge since it is light-weight and supposedly has the fewest legal concerns.
After you have conda installed, download conda_dgcode.yml and run the command:
conda env create -f conda_dgcode.yml
Note that since the requested conda environment in this case includes the rather sizeable Geant4 packages, it might take several minutes for this command to finish, and the resulting conda environment will consume several gigabytes of space (the exact number was around 3.8GB in February 2024).
Do not forget that you must activate your newly created environment before using it for the first time in a given terminal session:
conda activate dgcode
Alternatives for experts
The conda recipe above is intended to give a self-contained and reproducible
environment with not only dgcode itself, but also any required tools like
simplebuild, a Python interpreter, and
all the necessary build tools. For special advanced use cases, experts might
simply want to add the code itself into an environment where they otherwise have
ensured that all of these third-party tools are already available. In such a
case, one can simply install dgcode via pip, either via a PyPI package
(current version 
):
python3 -mpip install simple-build-dgcode
Or, directly from the latest dgcode sources at GitHub:
python3 -mpip install git+https://github.com/mctools/simplebuild-dgcode
With this latter approach, one can even install a specific commit id, branch, or
tag by appending @<gitid> to the URL in the last command. For instance:
python3 -mpip install git+https://github.com/mctools/simplebuild-dgcode@some_experimental_branch
Verifying an installation
As a verification of a dgcode installation, one can create a dgcode-based
simplebuild configuration and launch the unit tests from the
dgcode_val bundle (you can remove the leftover sbverify
directory afterwards):
$> conda activate dgcode
(dgcode) $> mkdir sbverify
(dgcode) $> cd sbverify
(dgcode) $> sb --init dgcode_val
sbld: Created simplebuild.cfg. If you wish you can edit it to fine-tune your configuration
(dgcode) $> sb --tests --requirepkg=DGCodeRecommended
sbld: Inspecting environment via CMake
-- Using CMAKE_BUILD_TYPE=Release
-- The C compiler identification is GNU 13.3.0
-- The CXX compiler identification is GNU 13.3.0
-- Detecting C compiler ABI info
<<
<< 866 LINES OF ACTUAL BUILD OUTPUT NOT SHOWN HERE >>
<<
Package G4Tests done
Creating python module GriffAnaUtils._init
Package GriffAnaUtils done
All done
make[1]: Leaving directory '/some/where/sbverify/simplebuild_cache/bld/makefiles'
sbld: Summary:
sbld:
sbld: Main bundle pkg root : /some/where/sbverify
sbld: Installation directory : /some/where/sbverify/simplebuild_cache/install
sbld: Build directory : /some/where/sbverify/simplebuild_cache/bld
sbld: Package search path : /some/where/sbverify (no pkgs)
sbld: ${CONDA_PREFIX}/lib/python3.11/site-packages/_simple_build_system/data/pkgs-core (1 pkgs)
sbld: ${CONDA_PREFIX}/lib/python3.11/site-packages/simplebuild_dgcode/data/pkgs_val (39 built, 1 skipped)
sbld: ${CONDA_PREFIX}/lib/python3.11/site-packages/_simple_build_system/data/pkgs-core_val (2 pkgs)
sbld: ${CONDA_PREFIX}/lib/python3.11/site-packages/simplebuild_dgcode/data/pkgs (55 built, 2 skipped)
sbld: System : Linux-6.5.0-1025-azure
sbld: Required dependencies : C[GNU/13.3.0] CMake[3.30.5] CXX[GNU/13.3.0]
sbld: Python[3.11.10] pybind11[2.13.6]
sbld: Optional dependencies present : DL[-] Fortran[GNU/13.3.0] Geant4[11.1.3]
sbld: NCrystal[3.9.7] Numpy[2.1.2] OSG[3.6.5] ZLib[1.3.1]
sbld: matplotlib[3.9.2]
sbld: Optional dependencies missing[*] : ASE Garfield Gemmi HDF5 Mantidpython Pandas
sbld: Pymatgen ROOT Scipy Spglib Threads mpmath
sbld: Package filter[*] : <none>
sbld: Build mode : release
sbld:
sbld: 97 packages built successfully : B10CommonTests BasicExamples BoronTube CXX11Tests
sbld: Core CoreLinkTests CoreTests DGCodeRecommended
sbld: DGCodeRecommendedNoGUI DMSCUtils DevTools
sbld: EvtFile ExportUtils ExprParser ExprParserTests
sbld: FmwkDev FortranExamples G4B10Common G4CollectFilters
sbld: G4CustomPyGen ... (77 more, supply --verbose
sbld: to see all)
sbld: 3 packages skipped due to [*] : RootUtils SH2RTests SimpleHists2ROOT
sbld:
sbld: Running tests in /some/where/sbverify/simplebuild_cache/bld/testresults:
sbld:
make[1]: Entering directory '/some/where/sbverify'
make[1]: Leaving directory '/some/where/sbverify'
sbld: ---------------------------------------+-----------+--------+----------+------------------
sbld: Test job results | Time [ms] | Job EC | Log-diff | Trouble info
sbld: ---------------------------------------+-----------+--------+----------+------------------
sbld: sb_b10commontests_test | 136 | OK | -- | --
sbld: sb_basicexamples_test_pyhelloworld | 84 | OK | OK | --
sbld: sb_basicexamples_testrunallexamples | 116 | OK | OK | --
sbld: sb_borontube_test | 3628 | OK | -- | --
sbld: sb_borontube_testchain | 5244 | OK | -- | --
sbld: sb_corelinktests_test | 12 | OK | -- | --
sbld: sb_coretests_testfile | 52 | OK | -- | --
sbld: sb_coretests_testformat | 20 | OK | -- | --
sbld: sb_coretests_testfpe | 24 | OK | -- | --
sbld: sb_coretests_testlibsymbols | 3472 | OK | -- | --
sbld: sb_coretests_testnodostxt | 1464 | OK | -- | --
sbld: sb_coretests_testpycpp | 164 | OK | -- | --
sbld: sb_coretests_testpylibsymbols | 4292 | OK | -- | --
sbld: sb_coretests_testpyquery | 212 | OK | -- | --
sbld: sb_coretests_testsdk | 4 | OK | -- | --
sbld: sb_coretests_teststring | 12 | OK | -- | --
sbld: sb_cxx11tests_test | 20 | OK | -- | --
sbld: sb_exprparsertests_testast | 40 | OK | -- | --
sbld: sb_exprparsertests_testbuilder | 12 | OK | -- | --
sbld: sb_exprparsertests_testtokenize | 8 | OK | -- | --
sbld: sb_fortranexamples_testfortranprog | 24 | OK | -- | --
sbld: sb_g4examples_testhooks | 820 | OK | OK | --
sbld: sb_g4exprparsertests_test | 188 | OK | -- | --
sbld: sb_g4geantinoinsrttests_test | 308 | OK | OK | --
sbld: sb_g4griffgentests_test | 316 | OK | -- | --
sbld: sb_g4mcpltests_testmcplgen | 296 | OK | OK | --
sbld: sb_g4mcpltests_testmcplwrite | 2680 | OK | OK | --
sbld: sb_g4plottests_testthermscat | 30256 | OK | -- | --
sbld: sb_g4tests_test_qgsp_bert_hp | 600 | OK | OK | --
sbld: sb_g4tests_test_qgsp_bic_hp | 476 | OK | OK | --
sbld: sb_g4tests_testcollect_f10 | 2640 | OK | OK | --
sbld: sb_g4tests_testcollect_m50 | 2748 | OK | OK | --
sbld: sb_g4tests_testcollect_r15 | 3100 | OK | OK | --
sbld: sb_g4tests_testcollect_r15_cpp | 2644 | OK | OK | --
sbld: sb_g4tests_testcollect_r15_volfilter | 3468 | OK | OK | --
sbld: sb_g4tests_testdatasets | 740 | OK | -- | --
sbld: sb_g4tests_testex | 2964 | OK | -- | --
sbld: sb_g4tests_testfilterex | 560 | OK | -- | --
sbld: sb_g4tests_testg4ncalloys | 3880 | OK | -- | --
sbld: sb_g4tests_testheatmap | 2340 | OK | -- | --
sbld: sb_g4tests_testidealgasbuilder | 108 | OK | -- | --
sbld: sb_g4tests_testlauncher | 220 | OK | -- | --
sbld: sb_g4tests_testmaterials | 228 | OK | -- | --
sbld: sb_g4tests_testpylist | 212 | OK | -- | --
sbld: sb_g4tests_testunitcompat | 112 | OK | -- | --
sbld: sb_g4vanilla_testimport | 180 | OK | -- | --
sbld: sb_g4vanilla_testrun | 948 | OK | -- | --
sbld: sb_generatortests_test_custompygen | 616 | OK | OK | --
sbld: sb_generatortests_test_custompygen2 | 464 | OK | OK | --
sbld: sb_generatortests_test_flexsimple | 284 | OK | -- | --
sbld: sb_generatortests_test_stdgenpars | 244 | OK | OK | --
sbld: sb_griffanaex_testcppana_advanced | 8 | OK | -- | --
sbld: sb_griffanaex_testcppana_basic | 28 | OK | -- | --
sbld: sb_griffanaex_testpyana_advanced | 96 | OK | OK | --
sbld: sb_griffanaex_testpyana_basic | 100 | OK | OK | --
sbld: sb_griffanatests_testextract | 748 | OK | OK | --
sbld: sb_griffanatests_testiter | 12 | OK | -- | --
sbld: sb_griffanatests_testiter_py | 212 | OK | OK | --
sbld: sb_griffdrtests_testevtfile_dbwriter | 8 | OK | -- | --
sbld: sb_griffdrtests_testevtfile_writer | 8 | OK | -- | --
sbld: sb_griffdrtests_testpartdef | 8 | OK | -- | --
sbld: sb_griffdrtests_testread | 20 | OK | -- | --
sbld: sb_griffdrtests_testread_minimal_py | 100 | OK | OK | --
sbld: sb_griffdrtests_testread_py | 192 | OK | OK | --
sbld: sb_griffdrtests_testread_reduced_py | 108 | OK | OK | --
sbld: sb_griffdrwtests_testf | 684 | OK | OK | --
sbld: sb_griffdrwtests_testm | 708 | OK | OK | --
sbld: sb_griffdrwtests_testr | 696 | OK | OK | --
sbld: sb_mcplpytests_testpya | 2840 | OK | OK | --
sbld: sb_mcplpytests_testpyb | 13488 | OK | OK | --
sbld: sb_mcplpytests_testpyc | 816 | OK | OK | --
sbld: sb_mcplpytests_testpyd | 18684 | OK | OK | --
sbld: sb_mcpltests_testcstds | 20508 | OK | OK | --
sbld: sb_mcpltests_testcxxstds | 20340 | OK | OK | --
sbld: sb_mcpltests_testflags | 9144 | OK | OK | --
sbld: sb_mcpltests_testforcemerge | 2148 | OK | OK | --
sbld: sb_mcpltests_testmiscphys | 20 | OK | OK | --
sbld: sb_mcpltests_testpystat | 860 | OK | OK | --
sbld: sb_mcpltests_testreadgzref | 4 | OK | -- | --
sbld: sb_mcpltests_testreadref | 8 | OK | -- | --
sbld: sb_mcpltests_testseek | 8 | OK | -- | --
sbld: sb_mcpltests_testtool | 1768 | OK | OK | --
sbld: sb_mcpltests_testtool_nogz | 2992 | OK | OK | --
sbld: sb_mcpltests_testwritegzip | 132 | OK | -- | --
sbld: sb_mcpltestsfmt2_testreadgzref | 4 | OK | -- | --
sbld: sb_mcpltestsfmt2_testreadref | 8 | OK | -- | --
sbld: sb_mcpltestsfmt2_testseek | 4 | OK | -- | --
sbld: sb_mcpltestsfmt2_testtool | 2184 | OK | OK | --
sbld: sb_mcpltestsfmt2_testtool_nogz | 3064 | OK | OK | --
sbld: sb_meshtests_test | 1596 | OK | -- | --
sbld: sb_meshtests_test2 | 896 | OK | -- | --
sbld: sb_meshtests_testcontentat | 8 | OK | -- | --
sbld: sb_meshtests_testreadref | 208 | OK | OK | --
sbld: sb_ncrystalreltests_testnamedmat | 4336 | OK | -- | --
sbld: sb_ncrystalreltests_teststdpy | 580 | OK | -- | --
sbld: sb_pkgdepcheck_testdeps | 96 | OK | -- | --
sbld: sb_plugutilstests_test | 12 | OK | -- | --
sbld: sb_pyanatests_test | 632 | OK | -- | --
sbld: sb_randtests_testrandutils | 8 | OK | -- | --
sbld: sb_scanutilstests_testskeleton | 34212 | OK | -- | --
sbld: sb_shutilstests_testsampler | 64 | OK | -- | --
sbld: sb_shutilstests_testsamplerpy | 704 | OK | OK | --
sbld: sb_simplehiststests_test | 8 | OK | -- | --
sbld: sb_simplehiststests_testmerge | 384 | OK | -- | --
sbld: sb_simplehiststests_testpy | 2228 | OK | OK | --
sbld: sb_skeletonsp_test | 2224 | OK | -- | --
sbld: sb_utilstests_testda | 36 | OK | -- | --
sbld: sb_utilstests_testmaxwell | 104 | OK | OK | --
sbld: sb_utilstests_testmurmurhash | 8 | OK | -- | --
sbld: sb_utilstests_testneutronmath | 100 | OK | OK | --
sbld: sb_utilstests_testnp | 192 | OK | OK | --
sbld: sb_utilstests_testparameterbase | 36 | OK | -- | --
sbld: sb_utilstests_testpsv | 452 | OK | -- | --
sbld: sb_utilstests_testreadnbrs | 24 | OK | -- | --
sbld: sb_utilstests_testtiepars | 132 | OK | OK | --
sbld: sb_utilstests_testunitpy | 208 | OK | -- | --
sbld: sb_zlibutilstests_testcompression | 16 | OK | -- | --
sbld: sb_zlibutilstests_testsdk | 4 | OK | -- | --
sbld: ---------------------------------------+-----------+--------+----------+------------------
sbld:
sbld: Test results are also summarised in: simplebuild_test_results_junitformat.xml
sbld:
sbld: All tests completed without failures!
sbld:
sbld: Build done. You are all set to begin using the software!
sbld:
sbld: To see available applications, type "sb_" and hit the TAB key twice.
sbld:
The important thing to notice here is that unit tests were launched, and the
message All tests completed without failures! tells us that they all
completed without problems. The --requirepkg=DGCodeRecommended argument,
ensures that all the most important third party software, like Geant4, NCrystal,
and Matplotlib, is also available on the system. If installing on a cluster
where you do not need any plotting or visualisation tools, you can use
DGCodeRecommendedNoGUI instead.
The unit tests above have one draw-back, in that they do mostly not test visualisation capabilities. So it is a good idea to manually test the Geant4 data and geometry viewer by launching the command:
$> sb_g4launcher_example --dataviewer -n1000
Which should give a view like the following (use the mouse to rotate the view):
In the image above, 4.4Å neutrons (green) hit a slab of aluminium from
above. The most prominent features in the image should be yellow lines going out
from the center into all directions, as well as green lines forming a cone. This
is because the scattering physics in the aluminium in this example is provided
by NCrystal as stdlib::Al_sg225.ncmat;comp=bragg (i.e. only Bragg
diffraction is enabled), so all (singly) scattered neutrons (green) should end
up in a single Debye-Scherrer cone. Other particles like gammas (yellow) are
generated in absorption events, based on Geant4’s own built-in physics.
Warning
There is a known issue on macOS where the viewer will either crash or only use part of the graphics window. There is a workaround described in this comment.
It might also be a good idea to verify that the Matplotlib-based SimpleHists plotting works, which can be done with the command:
$> sb_simplehists_browse -p G4CustomPyGen/example.shist
This should yield an interactive plot of the histogram found in the file (notice how hovering over a given bin creates a little light-blue transparent popup-box with detailed information about the bin):
You can also run the same command without -p to test that the SimpleHists
browser works:
$> sb_simplehists_browse G4CustomPyGen/example.shist
Which should launch an interactive browser looking like:
There is only 1 histogram inside this particular file, so the browser is not particular useful in this case. But you can still test that it works by confirming that clicking on the histogram results in that histogram being shown.