.. _sbnewsimproject: ********************************* 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``: .. include:: ../build/autogen_tricorder_newsimproj_help.txt :literal: 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): .. include:: ../build/autogen_tricorder_sbinit_plus_snippet_sb.txt :literal: 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): .. include:: ../build/autogen_tricorder_newsimproj_TriCorder.txt :literal: 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: .. include:: ../build/autogen_tricorder_newsimproj_sbtests.txt :literal: 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 :ref:`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 :ref:`visualising ` the simulation setup with the command ``sb_tricorder_sim --dataviewer -n100`` (or ``sb_tricorder_sim --viewer`` to get just the geometry): .. image:: images/tricorder_dataviewer.png :height: 250px :align: center | 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: :sbpkg:`TriCorder/G4GeoTriCorder/pycpp_GeoTriCorder/geometry_module.cc`: The implementation of the simulation geometry, including definition of modifiable parameters. :sbpkg:`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 :ref:`Griff ` files. In the :sbpkg:`same 'scripts' directory` you will also find more specialised scripts, which can be used to for instance create :ref:`parameter scans `. :sbpkg:`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 :ref:`Griff ` files. This analysis results in the production of a :ref:`SimpleHists ` file containing analysis histograms, which can then be opened for additional analysis, or simply browsed with the ``sb_simplehists_browse`` command. :sbpkg:`TriCorder/TriCorder/pkg.info` and :sbpkg:`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.