Installing-and-running-the-nsx-module.md

-Although installed as a dependency, the `pip` executable is not found after running `spack install`.
+## Prerequisites
 
-Activate the fenicsx environment and re-install pip explicitly
+First, create a Spack environment and install dolfinx following the instructions in https://git.lwp.rug.nl/chimera/habrok_hpc/-/wikis/Installing-dolfinx-with-spack-on-Habrok. We assume the environment is called `fenicsx`.
+
+## Installation and setup
+
+Clone the `nsx` git repository, here to the home directory:
 ```sh
-module load GCC
-spack env activate fenicsx
-srun -n 1 spack install --add py-pip
+cd && git clone https://git.lwp.rug.nl/chimera/nsx
 ```
-Clone the nsx git repo, here to the home directory:
+
+We will install `nsx` and its dependencies in a python [virtual environment](https://docs.python.org/3/tutorial/venv.html) (venv). Virtual environments allow us to install multiple versions of packages in an isolated fashion, avoiding conflicts. Create a `venv` called `fenicsx` in the folder `~/venv` (entirely arbitrary), *using python of the spack env*:
 ```sh
-cd && git clone https://git.lwp.rug.nl/chimera/nsx
+spack env activate fenicsx -p
+python3 -m venv --system-site-packages ~/venv/fenicsx 
+```
+Activate the virtual environment:
+```sh
+source ~/venv/fenicsx/bin/activate
 ```
-Install the nsx module (branch `main`, optionally in a virtual environment):
+Now install the `nsx` module (branch `main`) in the `venv` and spack env:
 ```sh
-cd ~/nsx
-module load GCC
-spack env activate fenicsx
-python3 -m venv --system-site-packages venv   # optional but recommended, path `venv` is arbitrary
-source venv/bin/activate                      # optional
-python3 -m pip install -e .[test]
+python3 -m pip install -U -e .[test]
 ```
 
-Add the location of `PetscBinaryIO.py` to the `PYTHONPATH`:
+## Running a simulation
+
+Steps to perform before running a simulation:
+
+1. Activate the Spack env and python venv:
+   ```sh
+   spack env activate fenicsx -p && source ~/venv/fenicsx/bin/activate
+   ```
+2. Add the location of `PetscBinaryIO.py` to the `PYTHONPATH`:
    ```sh
    export PYTHONPATH=$SPACK_ENV/.spack-env/view/lib/petsc/bin:$PYTHONPATH
    ```
+
 Run a test:
 ```sh
 cd ~/nsx/test
@@ -31,14 +43,18 @@ srun -n 1 python3 -m pytest -vvs analytical/test_poiseuille.py
 ```
 NOTE: Currently, not all tests succeed on the cluster.
 
-To run one of the Windkessel aorta examples:
+Run one of the Windkessel aorta examples:
 ```sh
 cd ~/nsx/test
 cp data/reference_windkessel_explicit_CT_np1/input.yaml aorta_wk_explicit.yaml
 srun -n 4 --mem=4GB nsx aorta_wk_explicit.yaml
 ```
 
-Alternatively, run this case via the sbatch job file [jobs/nsx_test.sh](https://git.lwp.rug.nl/chimera/habrok_hpc/-/blob/main/jobs/nsx_test.sh). If `nsx` was installed in a virtual environment, activate it in the job file.
+An example sbatch job file for this case is set up in [jobs/nsx_test.sh](https://git.lwp.rug.nl/chimera/habrok_hpc/-/blob/main/jobs/nsx_test.sh). The job file assumes that `nsx` was installed in a virtual environment as explained above.
+Execute it with:
+```
+sbatch jobs/nsx_test.sh
+```