From 09c97e15ff43883bbeaf98dbe38c4ed2a7dbae03 Mon Sep 17 00:00:00 2001
From: Antonio Ragagnin <antonio.ragagnin@inaf.it>
Date: Sat, 28 Dec 2024 02:24:24 +0000
Subject: [PATCH] Add new file
---
install_and_test.md | 52 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
create mode 100644 install_and_test.md
diff --git a/install_and_test.md b/install_and_test.md
new file mode 100644
index 0000000..4a0c46f
--- /dev/null
+++ b/install_and_test.md
@@ -0,0 +1,52 @@
+The components of `hotwheels` are stored in git repos. Each component has a python wrapper and both the python and C library can be installed using `pip`.
+Note that, as opposed to the typical `pip install`, the C compilation **will not** happen on `pip install`. The components will keep the source codes and they will be compiled on runtime. This has the benefit of allowing recompilation with different modules (as C and mpicc compilers), typical on HPC facilities.
+
+# The non-developer (easy) way
+
+For the user that is not going to edit the code and is only interested in running simulations, the process is very easy.
+
+For instance, to perform a simulation with particle mesh one can execute:
+
+```bash
+pip install 'hotwheels_PM[tested] @ git+ssh://git@git.ia2.inaf.it/hotwheels/PM.git@v0.0.0alpha'
+```
+
+This will install also the following hotwheels packages: core, io, timestep.
+The `[tested]` tag will install the versions of the dependencies used to test the release (`v0.0.0alpha` in this case).
+You can now test the installed modules running the `hotwheels.checkup` script that will execute all `test_*` C,python and bash files:
+
+```bash
+python -m hotwheels.checkup hotwheels
+```
+
+The tests will be run using envirnoment varialbe `CC` for the C ompiler (will default to `gcc`), `MPICC` for the MPI compiler (will default to `mpicc`), `CXX` and `MPICXX` for the c++ version (will default to `g++` and `mpicxx` respectively).
+
+The PM run needs the `gsl` and `fftw3` to be installed. They should be either in a standard path (`/usr/{lib,include}`) or in your compiler search path (namely, in your `C_INCLUDE_PATH`, `CPLUS_INCLUDE_PATH`, and `LD_LIBRARY_PATH` env variables).
+
+# Install custom release versions
+
+In case you want to run the module with other `hotwheel` component version you can install each manually:
+
+```bash
+pip install git+ssh://git@git.ia2.inaf.it/hotwheels/core.git@v0.0.0alpha
+pip install git+ssh://git@git.ia2.inaf.it/hotwheels/io.git@v0.0.0alpha
+pip install git+ssh://git@git.ia2.inaf.it/hotwheels/timestep.git@v0.0.0alpha
+pip install git+ssh://git@git.ia2.inaf.it/hotwheels/PM.git@v0.0.0alpha
+```
+
+# If you need to put hands on the source code
+
+In case you find that you need to edit the source code of hotwheels (maybe you found a bug), you
+can re-install a python module in editable mode. For instance, let's suppose that now you need to edit the timestep module and re-run all tests. You can do the following
+
+```bash
+pip install git+ssh://git@git.ia2.inaf.it/hotwheels/timestep.git@v0.0.0alpha
+cd timestep
+# very IMPORTANT the -e will install in editable mode
+# so you can change the module code and effects will take place
+# without need of uninstall and re-install
+pip install -e .
+# edit the file of your chise, for instance ./hotwheels/timestep/cosmo.c
+cd ..
+python -m hotwheels.checkup hotwheels #now the tests are run with the new ./hotwheels/timestep/cosmo.c
+```
--
GitLab