Added more compete examples, more detailed introduction

Author: peremato

tutorial/docs/01-introduction.ipynb

@@ -12,10 +12,27 @@
    "source": [
     "# Introduction to Geant4.jl\n",
     "\n",
-    "Geant4.jl provides the Julia bindings for the [Geant4](https://geant4.web.cern.ch) particle transportation toolkit. It is using [CxxWrap.jl](https://github.com/JuliaInterop/CxxWrap.jl) package to wrap C++ types and functions to Julia. Since the Geant4 toolkit is rather large and complex, writing the wrapper code by hand is not really an option. For this we use the package [WrapIt](https://github.com/grasph/wrapit) that automates the generation of the wrapper code making use of the clang library.\n",
+    "[Geant4.jl](https://github.com/JuliaHEP/Geant4.jl) provides the Julia bindings for the [Geant4](https://geant4.web.cern.ch) particle transportation toolkit. It is using [CxxWrap.jl](https://github.com/JuliaInterop/CxxWrap.jl) package to wrap C++ types and functions to Julia. Since the Geant4 toolkit is rather large and complex, writing the wrapper code by hand is not really an option. For this we use the package [WrapIt](https://github.com/grasph/wrapit) that automates the generation of the wrapper code making use of the clang library.\n",
     "\n",
     "Documentation of the concepts and how to write applications with the Geant4 toolkit can be found with the [Application Developer Guide](https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/index.html) or the [Classes and Members reference guide](https://geant4.kek.jp/Reference/11.2.0/index.html) for a detailed description of each C++ class. In this tutorial we will only highlight the differences between the Julia and the C++ API. Therefore it is assumed some prior knowledge of the Geant4 C++ interfaces.\n",
     "\n",
+    "## Why Julia?\n",
+    "The Julia programming language and ecosystem has a nice set of properties that are particularly effective for scientific workflows, in for particular simulation.\n",
+    "\n",
+    "Here are some of Julia’s properties\n",
+    "\n",
+    "- High-performance (usually within a factor of 0.5 of C; often at parity)\n",
+    "- Fully Unicode supporting - including LaTeX markup support in REPL, and natural mathematical symbols for common operations ($\\sin^2\\theta + cos^2\\theta = 1$)\n",
+    "- First-class support in Jupyter notebooks (it’s the Ju bit of the name)\n",
+    "- Supports generic programming (with multiple dispatch), functional-style method chaining, and other modern paradigms\n",
+    "- Dynamic typing, with efficient function specialisation (via JIT) and optional typing supported deeply in language (unlike Python)\n",
+    "- Has an excellent, robust package manager making installation and reproducible environments a breeze\n",
+    "\n",
+    "Julia is also just a really fun language to program in! \n",
+    "\n",
+    "## New to Julia?\n",
+    "There are many good tutorials and books for the Julia programming language. A [short introduction](https://juliahep.github.io/JuliaHEP-2023/intro.html) targeting people from high energy and nuclear physics with some experience with C++ has been put together by the JuliaHEP team.  Other tutorials can be found also [here](https://julialang.org/learning/tutorials/).\n",
+    "\n",
     "## Installation\n",
     "The Geant4.jl package does no require any special installation. Stable releases are registered to the Julia general registry, and therefore, it can be deployed with the standard `Pkg` Julia package manager.\n",
     "\n",
@@ -32,7 +49,7 @@
    "metadata": {},
    "source": [
     "## Wrapped classes\n",
-    "The notebook [02-wrapped-classes.ipynb](02-wrapped-classes.ipynb) introduces some basics for the interaction with the Geant4 wrapped classes. it is important to follow it in order to get familiar with some basic concepts and the mapping between the Julia and C++ constructs.  "
+    "The notebook [02-wrapped-classes.ipynb](02-wrapped-classes.ipynb) introduces some basics for the interaction with the Geant4 wrapped classes. It is important to follow it in order to get familiar with some basic concepts and the mapping between the Julia and C++ constructs.  "
    ]
   },
   {
@@ -58,6 +75,19 @@
     "- [11-event-display.ipynb](11-event-display.ipynb) - use the event display capability and learn how to customize it\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Complete examples\n",
+    "We have also a set of complete examples that combines all the elements described previously.\n",
+    "- [TestEm3.ipynb](examples/TestEm3/TestEm3.ipynb) - TestEm3 example. HEP calorimeter made of layers, implemented with user actions.\n",
+    "- [HBC30.ipynb](examples/HBC30/HBC30.ipynb) - CERN Liquid Hydrogen Bubble Chamber. It uses user actions and is able to display events that fullfil certain conditions (veto trigger)\n",
+    "- [WaterPhantom.ipynb](examples/WaterPhantom/WaterPhantom.ipynb) - Water Phantom Simulation with scoring meshes to obtain dose distributions.\n",
+    "- [B3a.ipynb](examples/B3/B3a.ipynb) - The example simulates schematically a Positron Emitted Tomography system. It uses a custom primary particle generator, a custom physics list and makes use of two sensitive detectors.\n",
+    "- [Scintillation.ipynb](examples/Scintillation/Scintillation.ipynb) - Example from the original at https://github.com/settwi/g4-basic-scintillation and adapted to the G4JL interface. Introduces optical photons and a custom physics list. It produces histograms as a result."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

tutorial/docs/02-wrapped-classes.ipynb

@@ -20,11 +20,7 @@
     "\n",
     "## Object instantiation\n",
     "\n",
-    "We start by instantiating some very simple object of type `G4Box`.\n",
-    "\n",
-    "Note that:\n",
-    "- the C++ constructor that is called is `G4Box::G4Box(const G4String &pName, G4double pX, G4double pY, G4double pZ)`\n",
-    "- the conversion of Julia type `Int64` to C++ `G4double` is implicit, as well as the `String` to `G4String` "
+    "We start by instantiating some very simple object of type `G4Box`."
    ]
   },
   {
@@ -43,6 +39,15 @@
     "box = G4Box(\"MyBox\", 1, 2, 3)  # the C++ contructor called G4Box (const G4String &pName, G4double pX, G4double pY, G4double pZ)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that:\n",
+    "- the C++ constructor that is called is `G4Box::G4Box(const G4String &pName, G4double pX, G4double pY, G4double pZ)`\n",
+    "- the conversion of Julia type `Int64` to C++ `G4double` is implicit, as well as the `String` to `G4String` "
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -177,7 +182,7 @@
    },
    "source": [
     "### Calling object methods\n",
-    "In julia, `methods` are instances of functions of a given name, of which the multi-dispatch functionality will select the best one that matches the actual argument types. To call a C++ method of a class we need to pass the wrapped object as first argument."
+    "In Julia, `methods` are instances of functions of a given name, of which the multi-dispatch functionality will select the best one that matches the actual argument types. To call a C++ method of a class we need to pass the wrapped object as first argument."
    ]
   },
   {
@@ -266,7 +271,7 @@
     "tags": []
    },
    "source": [
-    "### Working in the inheritance\n",
+    "### Working with inheritance\n",
     "In Geant4 all solid types inherit from a common base class `G4VSolid`. The method `Clone` returns a pointer to this base class.  "
    ]
   },
@@ -300,7 +305,7 @@
    },
    "source": [
     "### Object ownership\n",
-    "By default all objects instantiated by Julia will garbage collected (deleted) by Julia. this may pose problems with Geant4 since in many occasions the ownership is transferred implicitly to the toolkit, which will take care of doing a cleanup at the adequate moment. If we do nor pay attention we may get crashes (use a deleted objects and double deletions).\n",
+    "By default all objects instantiated by Julia will be garbage collected (deleted) by Julia. This may pose problems with Geant4 since in many occasions the ownership of the object is transferred implicitly to the toolkit, which will take care of doing a cleanup at the adequate moment. If we do not pay attention we may get crashes (use a deleted object or eventually double deletions).\n",
     "\n",
     "There are nevertheless some exceptions that have been added to simplify the interactions for the following classes: `G4PVPlacement`,\n",
     "`G4LogicalVolume`, `G4PVReplica`, `G4Material`, `G4Isotope`, `G4Element`, `G4JLParticleGun`, \n",
@@ -324,7 +329,7 @@
    "source": [
     "box1 = G4Box(\"box1\", 1,1,3)                                   # construct boxes\n",
     "box2 = G4Box(\"box2\", 1,3,1)                                  \n",
-    "union = G4UnionSolid(\"union\", CxxPtr(box1), CxxPtr(box2))     # construct a union solid with the same box\n",
+    "union = G4UnionSolid(\"union\", CxxPtr(box1), CxxPtr(box2))     # construct a union solid with the two boxes\n",
     "@show GetCubicVolume(union)\n",
     "@show DistanceToIn(union, G4ThreeVector(10,10,10))\n"
    ]
@@ -354,8 +359,8 @@
    },
    "outputs": [],
    "source": [
-    "box1 = box2 = nothing\n",
-    "GC.gc()\n",
+    "box1 = box2 = nothing                           # removed the reference to the G4Box objects\n",
+    "GC.gc()                                         # force a garbage collection now\n",
     "@show GetCubicVolume(union)                     # G4BooleanSolid cashes the volume\n",
     "# DistanceToIn(union, G4ThreeVector(10,10,10))  # this will probably crash the program"
    ]