From 6882cbc4ed65e3618530c3554886605269d8b9db Mon Sep 17 00:00:00 2001
From: Jan Mayer <jan.mayer@ikp.uni-koeln.de>
Date: Wed, 26 Feb 2020 22:02:54 +0100
Subject: [PATCH] Update Readme

---
 G4Batch.sh |  2 +-
 G4Horus.sh |  2 +-
 readme.md  | 95 ++++++++++++++++++++++++++++++++++++++++++++++++------
 3 files changed, 88 insertions(+), 11 deletions(-)

diff --git a/G4Batch.sh b/G4Batch.sh
index a96f6fa..25de92a 100755
--- a/G4Batch.sh
+++ b/G4Batch.sh
@@ -4,7 +4,7 @@ set -e
 
 ## Geant 4 Version
 # If a specific Geant4 version should be used, adapt and uncomment these lines.
-source /data/jmayer/software/geant4.10.05/bin/geant4.sh
+# source /data/jmayer/software/geant4.10.05/bin/geant4.sh
 echo "Using Geant4 Version `geant4-config --version` in `dirname $(dirname $(geant4-config --prefix))`"
 
 
diff --git a/G4Horus.sh b/G4Horus.sh
index 2cf0658..9de6f8f 100755
--- a/G4Horus.sh
+++ b/G4Horus.sh
@@ -10,7 +10,7 @@ export LIBGL_ALWAYS_INDIRECT=y
 
 ## Geant 4 Version
 # If a specific Geant4 version should be used, adapt and uncomment these lines.
-source /data/jmayer/software/geant4.10.05/bin/geant4.sh
+# source /data/jmayer/software/geant4.10.05/bin/geant4.sh
 echo "Using Geant4 Version `geant4-config --version` in `dirname $(dirname $(geant4-config --prefix))`"
 
 ## Build Project
diff --git a/readme.md b/readme.md
index 9700482..a96881e 100644
--- a/readme.md
+++ b/readme.md
@@ -1,21 +1,98 @@
 # G4Horus
 
-An implementation of the HORUS spectrometer geometry and detectors in Geant4.
+An implementation of the HORUS High-Purity Germanium (HPGe) γ-ray spectrometer and associated equipment in Geant4.
 
 ![G4Horus Default Geometry](doc/g4horus.png)
 
-## Quickstart
-1) On poseidon or gaia, create a new folder and do
 
-	git clone https://gitlab.ikp.uni-koeln.de/jmayer/g4horus.git .
-	./G4Horus.sh
+## Overview
 
-Note: On some systems, git will stumble over the SSL certificate, in this case use `git config --global http.sslVerify false` .
+The main goal of this project is to provide an accurate, easy-to-use efficiency simulation for the HORUS setup at the Institute for Nuclear Physics, University of Cologne.
+
+Components:
+
+- Geometries
+	- Target Chambers
+		- Astro Target Chamber
+		- Astro Target Chamber V2
+		- SONIC
+		- SONIC V3
+		- SONIC V3 ΔEE
+	- Setups (HPGe Arrays with positions for HPGe Detectors)
+		- HORUS (14)
+		- Cologne Clover Counting Setup (2)
+	- Detectors
+		- High-Purity Germanium (HPGe)*
+			- Coaxial (default)
+			- Clover
+			- Encapsulated Hexagonal
+		- Bismuth Germanate (BGO) anti-Compton shields
+		- [WIP] Passivated Implanted Planar Silicon (PIPS)
+	- Auxiliary equipment
+		- γ-Filter-Disks
+		- [NYI] Passive γ-Supershields
+- Actions
+	- Event Generators
+		- Particle Gun
+		- [WIP] Scattering Gun
+		- [NYI] Coincidence Gun
+	- Output Formats
+		- ROOT Histograms
+		- ROOT Ntuples (not recommended)
+		- SOCOv2 Events
+	- Evaluation
+		- Visualization Mode
+		- Batch processing Mode
+		- Automated efficiency evaluation
+
+\*) Note that each HPGe detector has unique properties, stored in the `DetectorLibrary`, and is referenced by its manufactured ID.
+
+
+## Getting Started
+
+### Dependencies
+- A not horribly outdated C++ build environment (`cmake` >= 3.11, `gcc` with C++11 support)
+- [Geant4](https://github.com/Geant4/geant4) >= 10.5
+  (make sure the proper environment variables are set, see example in `G4Horus.sh`
+- [CadMesh](https://github.com/christopherpoole/CADMesh/tree/v1.1) V1.1 (exactly!) and its dependencies
+
+### Installation
+
+```sh
+git clone https://gitlab.ikp.uni-koeln.de/jmayer/g4horus.git
+cd g4horus
+./G4Horus.sh
+```
 
 The project should compile and open a visual interface with a default view should open.
 
-2) Modify `src/DetectorConstruction.cc` to change the target chamber, detectors, and sensitve volumes. Use `./G4Horus.sh` to check your setup.
+### Quick Simulation
+
+- Run `./G4Batch.sh scripts/doit.mac` or other macro files to run the actual simulation.
+- Use `./efficiency.sh` to automatically extract efficiencies from the simulated data.
+
+
+## Constructing the Setup
+
+The experimental setup is assembled in `src/DetectorConstruction.cc`. Change the target chamber, detectors, and sensitive volumes here.
+Use `./G4Horus.sh` to check your setup.
+
+Example for equipping HORUS with detectors:
+
+```C++
+auto horus = new Horus(worldLV);
+// ID, Position, Distance (to endcap or filters on endcap), Filters
+// BGO Type, Position, Distance (to BGO or filters on bgo), BGO-Filters
+horus->PlaceDetector("73954", "Ge00", 20. * cm);
+horus->PlaceDetector(BGO::tSMALLNOSE, "BGO00", 10. * cm, {{"G4_Cu", 2. * mm}});
+```
+
+and the sensitive volumes [WIP]:
+
+```C++
+extern const std::vector<std::string> detectors = {"Ge00", "BGO00"};
+```
 
-3) Run `./G4Batch.sh` to run the actual simulation.
+Note that without setting the sensitive detector, no output will be recorded.
 
-4) Use `./efficiency.sh` to automatically extract efficiencys from the simulated data.
+The output type is set in `G4Batch.sh`, e.g. `-k hist` for histograms and `-k soco` for SOCOv2 events.