Update installation guide

README.md

@@ -20,21 +20,25 @@ GATE 10 introduces a Python-based interface, replacing the macro scripting of GA
 First, create a python environment:
 
 ```
-python -m venv opengate_env
+uv venv opengate_env
 source opengate_env/bin/activate
-pip install --upgrade pip
+python -m pip install --upgrade pip
 ```
 
-Then install the package opengate. The associated package ```opengate_core``` is automatically downloaded. ```opengate_core``` installs Geant4 librairies.
+(We recommend the Python package manager [`uv`](https://docs.astral.sh/uv/) because it creates isolated environments and makes Python version management easier.)
+
+Then install the package opengate:
 
 ```
-pip install opengate
+python -m pip install opengate
 ```
 
+The associated package ```opengate_core``` is automatically downloaded. ```opengate_core``` installs Geant4 librairies.
+
 If you already installed the packages and want to upgrade to the latest version:
 
 ```
-pip install --upgrade opengate
+python -m pip install --upgrade opengate
 ```
 
 Once installed, you can run all tests:
@@ -43,7 +47,7 @@ Once installed, you can run all tests:
 opengate_tests
 ````
 
-**WARNING (1)** The first time you run this command, the geant4 data and the test data will be downloaded. If the download fails (on some systems), try to add the following command before running opengate_tests:
+**WARNING (1)** The first time you run this command, the Geant4 data and the test data will be downloaded. If the download fails (on some systems), try to add the following command before running opengate_tests:
 
 ````
 export GIT_SSL_NO_VERIFY=1
@@ -54,8 +58,8 @@ All tests are in the folder [here](https://github.com/OpenGATE/opengate/tree/mas
 **WARNING (2)** Some tests (e.g. test034) needs [gaga-phsp](https://github.com/dsarrut/gaga-phsp) which needs [pytorch](https://pytorch.org/) that cannot really be automatically installed by the previous pip install (at least we don't know how to do). So, in order to run those tests, you will have to install both PyTorch and gaga-phsp first with:
 
 ````
-pip install torch
-pip install gaga-phsp
+python -m pip install torch
+python -m pip install gaga-phsp
 ````
 
 The test history can be visualized here: https://opengate.github.io/opengate_tests_results

docs/source/developer_guide/developer_guide_installation.rst

@@ -19,17 +19,33 @@ most tasks performed at initialization (before the run).
 Virtual environment
 -------------------
 
-:warning: It is highly, highly, *highly* recommended to create a python
-  environment prior to the installation, for example with
-  `venv <https://docs.python.org/3/library/venv.html#module-venv>`__.
-
-Example: You can create a new virtual environment via:
+.. tip:: It is highly, highly, *highly* recommended to create a Python environment prior to the installation.
 
 .. code:: bash
 
-     python -m venv --name opengate_env
+     python3 -m venv opengate_env
      source opengate_env/bin/activate
 
+You can also select a specific Python version:
+
+.. code:: bash
+
+     python3.11 -m venv opengate_env
+
+Then upgrade ``pip`` in the activated environment:
+
+.. code:: bash
+
+     python3 -m pip install --upgrade pip
+
+Make sure that the selected ``python3`` executable is one of the supported versions.
+
+Note: A virtual environment inherits the interpreter it was created from.
+To avoid this issue, consider using a Python package and project manager such as `uv <https://docs.astral.sh/uv/>`_ or `pixi <https://pixi.prefix.dev/latest/>`_ for creating environments because it makes it easy to manage distinct Python versions.
+
+Prepare the installation
+------------------------
+
 To **develop** in GATE 10, you need 1) to compile and create the
 ``opengate_core`` subpackage (this is the hardest part) and 2) install
 the main ``opengate`` package (Python only, fast and easy).
@@ -42,7 +58,7 @@ Then clone the unique repository that contains both packages:
    git clone --recurse-submodules https://github.com/OpenGATE/opengate
 
 :warning: When you update, the data for the tests must also be updated,
-  use : ``git submodule update --init --recursive``. This also update the
+  use : ``git submodule update --init --recursive``. This also updates the
   included subpackages (pybind11, etc).
 
 The subpackage ``opengate_core`` depends on the ITK and Geant4
@@ -111,7 +127,7 @@ Once it is done, you can compile ``opengate_core``.
 
    cd <path-to-opengate>/core
    export CMAKE_PREFIX_PATH=<path-to>/geant4.11-build/:<path-to>/itk-build/:${CMAKE_PREFIX_PATH}
-   pip install -v -e .
+   python -m pip install -v -e .
 
 The pip install will run cmake, compile the sources and create the
 module. If you are curious you can have a look the compilation folder in
@@ -131,7 +147,7 @@ The second part is easier : just go in the main folder and pip install:
 .. code:: bash
 
    cd <path-to-opengate>
-   pip install -v -e .
+   python -m pip install -v -e .
 
 STEP 5 - Before running
 -----------------------
@@ -170,9 +186,9 @@ pytorch and gaga-phsp first with:
 
 .. code:: bash
 
-   pip install torch
-   pip install gaga-phsp
-   pip install garf
+   python -m pip install torch
+   python -m pip install gaga-phsp
+   python -m pip install garf
 
 
 
@@ -181,7 +197,7 @@ Documentation for the documentation
 
 The document is created with `readthedoc <https://docs.readthedocs.io/en/stable/index.html>`_. To build the html pages locally, use `make html` in the `docs/` folder of the source directory. Configuration is in the `docs/source/conf.py` file. The current theme is `sphinx_pdj_theme <https://github.com/jucacrispim/sphinx_pdj_theme>`_.
 
-You also need to install some packages : ``pip install sphinx sphinx-copybutton pydata-sphinx-theme``
+You also need to install some packages : ``python -m pip install sphinx sphinx-copybutton pydata-sphinx-theme``
 
 Help with reStructuredText syntax:
 

docs/source/user_guide/user_guide_installation.rst

@@ -5,20 +5,22 @@ Install GATE with:
 
 .. code-block:: bash
 
-    python -m venv opengate_env
+    python3 -m venv opengate_env
     source opengate_env/bin/activate
-    pip install --upgrade pip
-    pip install opengate
+    python -m pip install --upgrade pip
+    python -m pip install opengate
 
 Then, you can create a simulation using the `opengate` module (see below). For **developers**, please check the `developer guide <../developer_guide/index.html>`_ for the developer installation.
 
-.. tip:: We highly recommend creating a specific Python environment to 1) ensure all dependencies are handled properly, and 2) avoid mixing with your other Python modules. For example, you can use `venv`.
+
+
+.. tip:: We highly recommend creating a specific Python environment to 1) ensure all dependencies are handled properly, and 2) avoid mixing with your other Python modules.
 
 If you already have `opengate` installed, upgrade it with:
 
 .. code-block:: bash
 
-    pip install --upgrade opengate
+    python -m pip install --upgrade opengate
 
 Once installed, we recommend checking the installation by printing GATE information and running the tests:
 
@@ -29,17 +31,30 @@ Once installed, we recommend checking the installation by printing GATE informat
 
 The first time a simulation is executed, Geant4 data must be downloaded and installed. This step is automated but may take some time depending on your bandwidth. Note that this is only done once. Running `opengate_info` will display details and the path of the data.
 
+GATE 10 is currently tested with Python 3.10 to 3.14.
+If you want to use a specific Python version, create the environment with an
+explicit interpreter, for example ``python3.11 -m venv opengate_env``.
+
+Note that ``venv`` inherits the system Python interpreter that was used when creating the virtual environment. To avoid this issue, consider using a Python package and project manager such as `uv <https://docs.astral.sh/uv/>`_ or `pixi <https://pixi.prefix.dev/latest/>`_ for creating environments because it makes it easy to manage distinct Python versions.
+
+Version without visualization
+-----------------------------
+
 For some systems (clusters or older computers), the main `opengate_core` cannot be used due to the lack of libGL or other visualization libraries. For Linux systems, we offer a version without visualization and using older libraries. You can install it with:
 
 .. code-block:: bash
 
-    python -m venv opengate_env
+    python3 -m venv opengate_env
     source opengate_env/bin/activate
-    pip install --upgrade pip
-    pip install opengate
-    pip install --force-reinstall "opengate[novis]"
+    python -m pip install --upgrade pip
+    python -m pip install "opengate[novis]"
+
+If you already installed the conventional `opengate` package in the same
+environment and want to switch to the ``novis`` variant, reinstall with:
+
+.. code-block:: bash
 
-Note that the option `--force-reinstall` is only needed if you already installed the conventional `opengate` before.
+    python -m pip install --force-reinstall "opengate[novis]"
 
 
 Additional help : `"Installing Gate 10 in Ubuntu 22 in WSL2 in Windows 11 AMD64" <https://drive.google.com/file/d/1lQW2u-935ev0l5oqt5MUDaLGhYRlanVB/view?usp=drive_link>`_