diff --git a/README.md b/README.md
index 77d701c5df2824114006728ed2e98db95385cf9d..d07d841334cc451206afbfd50f8293bac981e626 100644
--- a/README.md
+++ b/README.md
@@ -1,92 +1,318 @@
-# arti
+<div id="top"></div>
+<br />
+<div align="center">
+ <a href="https://github.com/lagoproject/arti">
+ <img src="./docs/images/lago-logo.png" alt="Logo" width="140">
+ </a>
+ <h3 align="center">The ARTI Framework</h3>
+ <p align="center">
+ A framework designed to simulate the signals produced by the secondary particles emerging from the interaction of the flux of primary cosmic ray with the atmosphere. These signals are simulated for any particle detector located at any place (latitude, longitude and altitude), including the real-time atmospheric, geomagnetic and detector conditions.
+ <br />
+ <!-- <a href="https://github.com/lagoproject/arti"><strong>Explore the docs (soon) »</strong></a>
+ <br /> -->
+ <br />
+ <!-- <a href="https://github.com/lagoproject/arti/issues">View Demo</a>
+ · -->
+ <a href="https://github.com/lagoproject/arti/issues">Request Feature</a>
+ ·
+ <a href="https://github.com/lagoproject/arti/issues">Report Bug</a>
+ ·
+ <a href="#Contact">Contact us</a>
+</p>
+</div>
+
+<!-- TABLE OF CONTENTS -->
+<details>
+ <summary>Table of Contents</summary>
+<br />
+ <ol>
+ <li><a href="#about-arti">About ARTI</a></li>
+ <li><a href="#getting-started">Getting Started</a></li>
+ <li><a href="#usage">Usage</a></li>
+ <li><a href="#related-projects">Related projects</a></li>
+ <li><a href="#proposed-features">Proposed Features</a></li>
+ <li><a href="#contributing">Contributing</a></li>
+ <li><a href="#license">License</a></li>
+ <li><a href="#contact">Contact</a></li>
+ </ol>
+</details>
+
+<!-- ABOUT THE PROJECT -->
+## About ARTI
+<!--
+<style>
+html, body {height: 100%;}
+img {
+height: auto;
+width: auto;
+}
+img.rel {
+ width: 33%;
+}
+</style>
+-->
+
+<img class="rel" src="./docs/images/flux-chacaltaya.png" alt="The seconday particle flux at Chacaltaya" width="200"><img class="rel" src="./docs/images/geomagnetic.png" alt="Charged particles trajectories" width="200"><img class="rel" src="./docs/images/wcd-muon.png" alt="A muon traversing the WCD " width="200">
+
+ARTI is a complete framework designed to simulate the signals produced by the secondary particles emerging from the interaction of singles, multiple and even the complete flux of primary cosmic rays with the atmosphere. These signals are simulated for any particle detector located at any place (latitude, longitude and altitude), including the real-time atmospheric, geomagnetic and detector conditions.
+
+Formulated through a sequence of scripts coded in C++, Fortran, and Perl, it provides an easy-to-use integration of three different simulation environments: [Magneto Cosmics](http://cosray.unibe.ch/~laurent/magnetocosmics/), [CORSIKA](https://www.iap.kit.edu/corsika/) and [Geant4](https://geant4.web.cern.ch/). These tools evaluate the geomagnetic field effects on the primary flux, the atmospheric showers of cosmic rays and the detectors' response to the secondary flux of particles produced in the atmosphere.
+
+With ARTI it is also possible to calculate the flux of the expected signals produced by the sudden occurrence of a gamma-ray bursts or the flux of energetic photons originating in steady gamma sources. It also compares these fluxes with the expected background to detect these phenomena in a single water Cherenkov detector (WCD).
+
+Even more, by using ARTI, it is possible to calculate in a very precise way the expected flux of high energetic muons and other secondaries on the ground and to inject it over a geological structure for muography applications.
+
+### ARTI main reference and citation
+
+When using ARTI, please cite the reference reported below:
+
+Christian Sarmiento-Cano, Mauricio Suárez-Durán, Rolando Calderón-Ardila, Adriana Vásquez-RamÃrez, Andrei Jaimes-Motta, Luis A. Núñez, Sergio Dasso, Iván Sidelnik and Hernán Asorey (for the LAGO Collaboration), _"The ARTI Framework: Cosmic Rays Atmospheric Background Simulations"_, _European Journal of Physics_ **C**, submitted, [arXiv:2010.14591[astro-ph.IM]](https://arxiv.org/abs/2010.14591), [doi:10.48550/arXiv.2010.14591](https://doi.org/10.48550/arXiv.2010.14591) (2022).
+[(bibtex)](docs/references/arti.bib)
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- GETTING STARTED -->
+## Getting Started
+
+To get a local copy up and running follow these simple example steps.
+
+### Prerequisites
+
+#### System requirements
+
+ARTI runs in any Linux based system, including iOS. For Windows user, we strongly recommend to install some of your preferred linux distribution using virtualbox. Additionally, we are developing a docker-based ARTI implementation.
+
+In Fedora, Scientific Linux and CentOS, use `sudo yum install <package>`. In Ubuntu/Debian, use `sudo apt install <package>`. In both cases, you can also use the graphic package manager included in your preferred distro.
+
+ARTI requires the installation of the following packages:
+
+* bash
+* perl 5.0
+* gcc
+* make
+* screen
+* rsync
+* git
+
+As a one-liner for Ubuntu/Debian:
+
+```bash
+sudo apt install build-essential screen rsync git
+```
+(git is optional).
+
+#### Dependencies
+Additionally, ARTI depends on the previous installation of the following frameworks:
+* [CORSIKA v7.7402](https://www.iap.kit.edu/corsika/79.php).
+* [ROOT v6.20.08](https://root.cern/releases/release-60802/).
+* [Magneto Cosmics v2.0](http://cosray.unibe.ch/~laurent/magnetocosmics/).
+* [Geant v4.10.03.p03](https://geant4.web.cern.ch/support/download_archive?page=4)
+* [Geant v4.10.03 Data Libraries](https://geant4.web.cern.ch/support/download_archive?page=4)
-## Getting started
+Plese notice this list corresponds to the set of external dependencies of ARTI v1r9. Backward compatibility within previous minor versions and patches of the external dependencies is assured, i.e., ARTI will run with any older versions of CORSIKA v7.xxxx, ROOT v6.xx.xx and GEANT4.10.xx.xx.pxx.
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+CORSIKA should be compiled with the following options:
+```
+Compiler: 64bits
+High Energy Hadronic Model: QGSJETII-04
+Low Energy hadronic interaction model: GHEISHA 2002d
+Detector Geometry: non-flat (Volume) detector
+```
+and, for production, the following additional program options:
+```
+Landau-Pomeranchunk-Migdal (LPM) effect
+Curved atmosphere version
+external atmosphere functions
+EFIELD
+```
+Additionally, ARTI is compatible with some other CORSIKA functionalities, such as ```PLOTSH```, ```PLOTSH2```. and ```CHERENKOV```, but it is not recommended to compile CORSIKA using these options as they will strongly decrease the simulation performance and are not needed for production.
+A pre-compiled version of CORSIKA intended for simulation production is available [upon request](#Contact).
+
+There are no other special requirements for ROOT, MAGNETOCOSMICS and GEANT4. Standard installations of these packages will smoothly work with ARTI.
+
+### Installation
+
+1. If you are using git, just clone this repository:
+ ```bash
+ cd /path/to/ARTI/installation
+ git clone https://github.com/lagoproject/arti.git
+ ```
+ Otherwise, you can also directly download ARTI without using git (in this case, you should reinstall ARTI for every upgrade):
+ ```bash
+ cd /path/to/ARTI/installation
+ wget -c https://github.com/lagoproject/arti/archive/refs/heads/master.zip
+ unzip master.zip
+ rm master.zip
+ ```
+2. ARTI compiling is very simple:
+ ```bash
+ cd arti
+ make
+ ```
+ 1. During the first installation of ARTI (or if you need to install ARTI in a different directory), `make` will define the `$ARTI` environment variable, that points to the ARTI current directory installation. Then, ARTI installer will add the definition of this variable to the user's local `.bashrc` and to the local `$PATH` environment variable:
+ ```bash
+ #
+ ## Changes added by the ARTI suite on <installation date>
+ #
+ export ARTI="/path/to/ARTI/installation/arti"
+ export PATH="${ARTI}/sims/:${ARTI}/analysis:$PATH"
+ ```
+ You can edit your `.bashrc` to add, e.g., the directory where the CORSIKA executables files were located, for example:
+ ```bash
+ export CRK="/path/to/CORSIKA/run"
+ export PATH="${CRK}/:$PATH"
+
+If you follow the above described steps and everything works well, you should find some new executable files at the `${ARTI}/analysis` directory.
+
+### Pre-compiled ARTI framework (inc. dependencies)
+
+A Docker container having all the ARTI requirements and dependencies installed and configured with the corresponding options for production is currently under development and will be available in June 2022.
+
+If you want to receive information about the ARTI new releases, or have any doubts or require extra information about the compiling options for all these packages, please don't hesitate to [contact us](#Contact).
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+### ARTI updates, releases, branchs and tags
+
+ARTI is continously used, revised and updated within the [LAGO Collaboration](https://lagoproject.net).
+
+Unless you are a developer, we recommend to use only the latest ARTI release contained in the `master` branch of this repository. Stable versions are tagged and can be found in the [corresponding section of this repository](https://github.com/lagoproject/arti/tags).
+
+Clone and install ARTI from `dev` or `dev-*` branches is strongly discouraged, as these branches are used for testing, bug correction and for the development of new features.
+
+If you are using `git`, you can update ARTI just by doing:
+
+```bash
+cd /path/to/ARTI/installation/arti
+git pull
+make
+```
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+Otherwise, you could just reinstall ARTI by following the [installation guide](#installation).
-## Add your files
+<p align="right">(<a href="#top">back to top</a>)</p>
-- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
+## Usage
+The ARTI approach for calculation the expected flux of signals due to the integrated flux of cosmic rays is based on three stages:
+
+1. Definition of the site characteristics, primary spectrum calculations and [Extensive Air Showers (EAS](https://en.wikipedia.org/wiki/Air_shower_(physics))) developments;
+2. Analysis of the secondary particles at ground and geomagnetic corrections;
+3. Detector simulation.
+
+Depending on the type of calculation the user should need, there are different pathways that need to be followed.
+
+### Flux calculation basis
+
+#### a. Expected flux of secondaries at ground level
+
+The flux simulation background starts with the `do_sims.sh` script, as follows:
+
+```bash
+do_sims.sh -w path_to/corsika/run/ -p fluxBGA -s bga -v 77402 -t 3600 -u orcid -y -x
```
-cd existing_repo
-git remote add origin https://gitmilab.redclara.net/halleyUIS/arti.git
-git branch -M main
-git push -uf origin main
+With this options, ARTI will integrate the expected flux of primaries during 3600 second (`-t 3600`) for the city of Bucaramanga, Colombia (`-s bga`) at an altitude of 965 m a.s.l., using a volumetric WCD (`-y`). EAS calculations will be done using the CORSIKA executables version 7.7402 (`-v 77402`) located at `-w path_to/corsika/run`. The user [ORCID](https://orcid.org/) (-u `orcid`) will be stored in the corresponding metadata and will be preserved for future citation of the data. While it is recommended to use your ORCID, any alphanumeric string is accepted. For the rest of possible options, do_sims.sh will use the ARTI defaults (`- x`). Otherwise, they would be answered in an interactive ARTI session.
+
+The list of predefined sites in ARTI is compiled and regularly updated in [the LAGO Data Management Plan](https://lagoproject.github.io/DMP/defs/sitesLago/). ARTI includes a JSON parser to get the characteristics needed for the simulation of the flux at several predefined sites.
+
+Defaults, included the site characteristics, can be overridden by the user by selecting the corresponding options. Please run
+```bash
+do_sims.sh -?
+```
+to view a brief description of the available options.
+The resulting files will be stored at the local directory `/path_to/corsika/run/fluxBGA`, automatically created from the path given with the `-w` option and the project name (`-p fluxBGA`).
+
+The scripts and codes related with these calculations can be found in the [sims](sims) directory. All of them have their own integrated help, accessible through the `-?` modifier.
+
+#### b. Analysis of the secondaries and geomagnetic effects
+
+Once the catalogues with the raw data of the flux are produced, they can be read and analysed with the ARTI analyses tools to extract the secondary particle flux information: the secondary particle ID, the particle momentum, the particle position relative to the primary core, and additional information related with its primary progenitor.
+Depending on the environment, the analysis stage can be performed automatically during the runtime or manually by calling to the `do_showers.sh` script:
+
+```bash
+$ do_showers.sh -o /path_to/corsika/run/fluxBGA -k 965 -t 3600 -g bga.geo 3 -l
```
+With this options, ARTI will perform the standard analysis of the files located at `/path_to/corsika/run/fluxBGA` (`-o` option), corresponding to the flux of secondaries impinging 1 m2 at ground during 3600s (`-t` option) for a site at an altitude of 965 m a.s.l. (`-k` option), using the column 3 of the geomagnetic conditions file `bga.geo` (`-g` option). The analysis will be parallelized (`-l`) using the default number of processors equals to half the available ones, and the results will be stored in the current directory (default: `$PWD`, see option `-w`).
-## Integrate with your tools
+As in the previous case, all the codes and executables have their internal help (`-?`) and are available in the [analysis](analysis) directory.
-- [ ] [Set up project integrations](https://gitmilab.redclara.net/halleyUIS/arti/-/settings/integrations)
+#### c. Water Cherenkov Detector Simulation
-## Collaborate with your team
+A complete and detailed simulation of a generic and modifiable WCD Geant4 simulation is included in the [wcd](wcd) directory.
-- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
-- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
-- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
+The main characteristics of the detector can be easily configured by editing the corresponding files in the [src](wcd/src), such as: the water container material, thickness and geometry; the reflectivity and diffusivity of the detector's inner coating; the water absorption curves in the optical and UV wavelength range; the geometry and wavelength sensitivity of the photomultiplier tube (PMT); and the emulated response of the onboard electronic system.
-## Test and Deploy
+Once the corresponding variables are updated in the code, it must be re-compiled by doing:
+```bash
+cmake -DGeant4_DIR=/path/to/geant4/lib/Geant4-version/
+make -j2
+```
+and a new `wcd` executable file will be compiled at the `wcd` directory.
+Before to run, the file containing the secondaries at ground resulting of the previous analisys should be defined in the `input.in` file.
-Use the built-in continuous integration in GitLab.
+Again, depending on the environment, it could run automatically during runtime or has to be called by the user once the previous stages are completed, by doing:
+```bash
+wcd -m input.in > run.log
+```
-- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
+Additional information can be found in the wcd module [`README.md`](wcd/README.md) and in the [ARTI Documentation](docs).
-***
+### General help and documentation
-# Editing this README
+The documentation is currently under preparation and will be released in July 2022. A brief description of the action of each code and the available options and modifiers can be seen by calling them with the `-? modifier`.
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.
+_For more examples, please refer to the [ARTI Documentation](docs)._
-## Suggestions for a good README
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+<p align="right">(<a href="#top">back to top</a>)</p>
-## Name
-Choose a self-explaining name for your project.
+## Related projects
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+ARTI has several options and internal configurations to automatically run at different types of computing facilities: from personal notebooks or desktops up to high performance computing clusters.
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+More recently, [oneDataSim](https://github.com/lagoproject/onedataSim), a cloud-based implementation of ARTI, has been developed under the [LAGO Thematic Service](https://www.eosc-synergy.eu/supporting-astrophysics/) at the [_European Open Science Cloud - Expanding Capacities by building Capabilities_](https://www.eosc-synergy.eu/) project.
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+By using [oneDataSim](https://github.com/lagoproject/onedataSim), currently available through the [EOSC Marketplace](https://marketplace.eosc-portal.eu/services/onedatasim), it is possible to run the ARTI simulations at federated clouds, such as the [European Open Scientific Cloud (EOSC](https://eosc-portal.eu/)) and other public clouds, such as the [Google cloud](https://cloud.google.com/),[ Amazon web services](https://aws.amazon.com/) and [Microsoft Azure](https://azure.microsoft.com/).
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+<p align="right">(<a href="#top">back to top</a>)</p>
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+## Proposed features
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+See the [open issues](https://github.com/lagoproject/arti/issues) for a full list of proposed features (and known issues).
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
+<p align="right">(<a href="#top">back to top</a>)</p>
+<!-- CONTRIBUTING -->
## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
+Don't forget to give the project a star! Thanks again!
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- LICENSE -->
## License
-For open source projects, say how it is licensed.
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+ARTI is distributed under the [BSD-3 License](https://opensource.org/licenses/BSD-3-Clause). See the [LICENCE](LICENSE) for more information.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- CONTACT -->
+## Contact
+
+The ARTI framework is developed by the LAGO simulation group. If you need to contact us, please complete our [contact form](https://lagoproject.net/contact.html).
+
+ARTI principal contact: [Dr. Hernán Asorey (@asoreyh)](https://github.com/asoreyh)
+
+Project Link: [https://github.com/lagoproject/arti](https://github.com/lagoproject/arti)
+
+<p align="right">(<a href="#top">back to top</a>)</p>