Starting a new simulation project

It can admittedly be a bit daunting for new users to get started on implementing their own simulation project. For that reason, we have created a little helpful (hopefully) utility, which based on a user-supplied project name helps the users setting up all the necessary files and directories required to add a few simplebuild packages containing a little trivial example of how to setup and analyse a Geant4 simulation. The user can then get started quickly, simply by modifying the example.

The command to use is dgcode_newsimproject:

$> dgcode_newsimproject -h
usage: dgcode_newsimproject [-h] [-d DIR] PROJECTNAME

Creates, and populates with skeleton code, new packages for a simulation
project

positional arguments:
  PROJECTNAME           Project name. Should be short and descriptive
                        CamelCased string with no spaces

options:
  -h, --help            show this help message and exit
  -d DIR, --target_dir DIR
                        Target directory. Defaults to <root>/PROJECTNAME where
                        <root> is the pkg-root associated with your main
                        simplebuild.cfg file.

For the sake of the following discussions, we will assume you are creating a completely fresh working directory in which you wish to work (this might of course not be the case). Thus, first create a new empty directory, step into it and use sb --init dgcode to setup a new simplebuild and dgcode-based bundle in which you can create packages for your project. Technically, the command creates an appropriate simplebuild.cfg file which will serve as the main cfg file whenever you later invoke the sb command (more details available here and here). Next, configure and build everything by typing the command sb (this might take a few minutes to complete):

$> sb --init dgcode
sbld:  Created simplebuild.cfg. If you wish you can edit it to fine-tune your configuration
$> sb
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
<<
<< 581 LINES OF ACTUAL BUILD OUTPUT NOT SHOWN HERE >>
<<
sbld:
sbld:  Type the following command (exactly) to do so (undo later by --env-unsetup instead):
sbld:
sbld:      eval "$(sb --env-setup)"
sbld:

So assuming we want a project to investigate the properties of a new amazing detector technology, named “tricorder”, we then proceed by using the dgcode_newsimproject command (please try to use CamelCasing for project names):

$> dgcode_newsimproject TriCorder
Created file: TriCorder/G4GeoTriCorder/pkg.info
Created file: TriCorder/G4GeoTriCorder/pycpp_GeoTriCorder/geometry_module.cc
Created file: TriCorder/TriCorder/app_ana/analysis_program.cc
Created file: TriCorder/TriCorder/pkg.info
Created file: TriCorder/TriCorder/scripts/scan
Created file: TriCorder/TriCorder/scripts/scanana
Created file: TriCorder/TriCorder/scripts/sim
Created file: TriCorder/TriCorder/scripts/simanachain
Created file: TriCorder/TriCorder/scripts/test

Created 9 new files from the simulation project skeleton under

        /some/where/autogen_tricorder_projdir/TriCorder

Now you can go carefully through them and replace their contents as needed for
your project.

Do not forget to update documentation in comments and pkg.info files!

Make sure that you have edited all files, and that everything is tested with at
least "sb --tests" before committing anything to a shared repository!

As written, new packages and files have been created for you in your local directory (defaulting to the directory of your main simplebuild.cfg file). Of course, if you are working with code in a shared repository (e.g. at GitHub), nothing has been added to the remote repository at this point. Nor should it, since having multiple essentially identical copies of the same example in a shared repository is not very useful. Rather, you are now expected to modify the files as appropriate for your actual project before finally git add’ing and committing and pushing them to the central repository server. If these terms are obscure to you, you should most likely spend some time learning about Git, for instance here or here.

For now, you can immediately type sb to ensure that the newly added files get built, or even sb --tests to also run the associated unit tests:

$> sb --tests
sbld:  Disabled 2 packages due to missing external dependencies
sbld:  Configuration completed => Launching build with 4 parallel processes
make[1]: Entering directory '/some/where/autogen_tricorder_projdir/simplebuild_cache/bld/makefiles'
[94mBuild started[0m
  Generating G4GeoTriCorder/__init__.py
  Updating symlinks G4GeoTriCorder/testlogs
  Updating symlinks TriCorder/scripts
  Updating symlinks TriCorder/testlogs
Installing global system modules
  Building G4GeoTriCorder/pycpp_GeoTriCorder/geometry_module.o
  Building TriCorder/app_ana/analysis_program.o
  Creating application sb_tricorder_ana
Package TriCorder done
  Creating python module G4GeoTriCorder.GeoTriCorder
Package G4GeoTriCorder done
All done
make[1]: Leaving directory '/some/where/autogen_tricorder_projdir/simplebuild_cache/bld/makefiles'
sbld:  Summary:
sbld: 
sbld:    Main bundle pkg root             : /some/where/autogen_tricorder_projdir
sbld:    Installation directory           : /some/where/autogen_tricorder_projdir/simplebuild_cache/install
sbld:    Build directory                  : /some/where/autogen_tricorder_projdir/simplebuild_cache/bld
sbld:    Package search path              : /some/where/autogen_tricorder_projdir (2 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 (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[-] Geant4[11.1.3] NCrystal[3.9.7] Numpy[2.1.2]
sbld:                                       OSG[3.6.5] ZLib[1.3.1] matplotlib[3.9.2]
sbld:    Optional dependencies missing[*] : ASE Fortran Garfield Gemmi HDF5 Mantidpython
sbld:                                       Pandas Pymatgen ROOT Scipy Spglib Threads
sbld:                                       mpmath
sbld:    Package filter[*]                : <none>
sbld:    Build mode                       : release
sbld:  
sbld:    58 packages built successfully   : Core DGCodeRecommended DGCodeRecommendedNoGUI
sbld:                                       DMSCUtils DevTools EvtFile ExportUtils ExprParser
sbld:                                       G4B10Common G4CollectFilters G4CustomPyGen
sbld:                                       G4DataCollect G4ExprParser G4GeantinoInserter
sbld:                                       G4GeoTriCorder G4GravityHelper G4GriffGen
sbld:                                       G4HeatMap G4Interfaces G4Launcher ... (38 more,
sbld:                                       supply --verbose to see all)
sbld:    2 packages skipped due to [*]    : RootUtils SimpleHists2ROOT
sbld: 
sbld:  Running tests in /some/where/autogen_tricorder_projdir/simplebuild_cache/bld/testresults:
sbld: 
make[1]: Entering directory '/some/where/autogen_tricorder_projdir'
make[1]: Leaving directory '/some/where/autogen_tricorder_projdir'
sbld:   ---------------------------------------+-----------+--------+----------+------------------
sbld:    Test job results                      | Time [ms] | Job EC | Log-diff | Trouble info
sbld:   ---------------------------------------+-----------+--------+----------+------------------
sbld:    sb_tricorder_test                     |    1260   |   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. To use the resulting environment you must first enable it!
sbld: 
sbld:  Type the following command (exactly) to do so (undo later by --env-unsetup instead):
sbld: 
sbld:      eval "$(sb --env-setup)"
sbld: 

Editing the generated files

The pre-filled example inside the files consists of a simple setup in which neutrons hit a spherical sample and get recorded on a box-shaped detector. Running the simulation and analysis with default values will result in histograms (in a SimpleHists file) representing the “detected” hitmap, in which Debye-Scherrer cones from the polycrystalline sample material can be observed. It might be useful to start by visualising the simulation setup with the command sb_tricorder_sim --dataviewer -n100 (or sb_tricorder_sim --viewer to get just the geometry):

The most interesting files in our TriCorder project, and the files you especially need to focus on when editing, are discussed in the following. Note that for technical reasons the links below points to files in a project called “SkeletonSP” instead of “TriCorder”, but apart from the naming there is no difference:

TriCorder/G4GeoTriCorder/pycpp_GeoTriCorder/geometry_module.cc:: The implementation of the simulation geometry, including definition of modifiable parameters.
TriCorder/TriCorder/scripts/sim:: The simulation script which puts together our geometry with a generator and becomes the command sb_tricorder_sim, which can be used to launch the simulation, or visualise it. Run the command sb_tricorder_sim -h to learn more about the possibilities. The output of the simulation is one or more Griff files. In the same ‘scripts’ directory you will also find more specialised scripts, which can be used to for instance create parameter scans.
TriCorder/TriCorder/app_ana/analysis_program.cc:: An analysis program which can be invoked via the command sb_tricorder_ana and which is used to analyse the Griff files. This analysis results in the production of a SimpleHists file containing analysis histograms, which can then be opened for additional analysis, or simply browsed with the sb_simplehists_browse command.
TriCorder/TriCorder/pkg.info and TriCorder/G4GeoTriCorder/pkg.info :: The pkg.info files should contain a bit of general information about what your simulation project is about, which people are involved with it, etc.

Of course, you should only Git commit some or all of these files once you have actually edited them somewhat as suits your project. After all, you are most likely not interested in filling up your Git repository with 10 copies of what is essentially the same simple example, only differing in naming.