Skip to content

Commit 5a9763d

Browse files
ddundojoewallwork
andauthored
Wiki: Clarify installation instructions; add PETSc reconfigure section (#130)
I think it would be good to further expand and clarify the installation instructions in the wiki: - I added a section on how to reconfigure an existing PETSc installation. I think this is useful since I assume that many users will already have an existing installation - I clearly separated the "local install" and "Docker" approaches and their differences. I thought that it was slightly confusing in its current state. - I now explicitly state that the Docker image has everything pre-installed and ready to use. - I put the section on Docker at the very end, so that it is not intertwined with the 'local installation' approach - I simplified the 'Installing Mesh Adaptation modules' section with various minor changes (will leave comments on specific changes) --------- Co-authored-by: Joe Wallwork <22053413+jwallwork23@users.noreply.github.com>
1 parent b14fe31 commit 5a9763d

1 file changed

Lines changed: 42 additions & 37 deletions

File tree

wiki/Installation-Instructions.md

Lines changed: 42 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
The following installation instructions assume a Linux or Windows Subsystem for Linux (WSL) operating system.
2-
The mesh adaptation modules are dependent on a custom setup for Firedrake with PETSc from either a [local installation](#local-firedrake-installation) or a [pre-built Docker image](#installing-firedrake-via-docker-image).
3-
Once Firedrake is installed (or if you already have a working installation), see the section on [installing Animate, Goalie, or Movement](#installing-animate-goalie-or-movement).
2+
3+
The mesh adaptation modules are dependent on a custom setup for Firedrake with PETSc, as described in the [local installation](#local-firedrake-installation) section below. Once Firedrake is installed, see the section on [installing Animate, Goalie, or Movement](#installing-animate-goalie-or-movement).
4+
5+
Alternatively, you may use a [pre-built Docker image](#docker-container-approach) with Animate, Goalie, Movement, and all their dependencies preinstalled and ready to use.
46

57
## Local Firedrake installation
68

@@ -14,17 +16,53 @@ To use the mesh adaptation modules, we can install system dependencies (step 1)
1416
python3 ../firedrake-configure --show-petsc-configure-options | xargs -L1 ./configure --download-eigen --download-parmetis --download-mmg --download-parmmg
1517
```
1618

19+
### Reconfiguring an existing installation
20+
21+
If you have previously installed PETSc without the additional mesh adaptation packages listed above, you can install them using PETSc's [reconfigure](https://petsc.org/release/install/multibuild/#reconfigure) script as follows:
22+
```
23+
cd $PETSC_DIR
24+
$PETSC_DIR/$PETSC_ARCH/lib/petsc/conf/reconfigure-$PETSC_ARCH.py --download-eigen --download-parmetis --download-mmg --download-parmmg
25+
make PETSC_DIR=${PETSC_DIR} PETSC_ARCH=${PETSC_ARCH} all
26+
```
27+
28+
## Installing Mesh Adaptation modules
29+
30+
The Mesh Adaptation packages Animate, Goalie, and Movement are installed as follows, denoting the package of interest by `<PACKAGE>`.
31+
First, ensure that you have activated the Python virtual environment associated with your Firedrake installation:
32+
```
33+
source /path/to/venv/bin/activate
34+
```
35+
36+
Then clone the `<PACKAGE>` repository using [your preferred method](https://docs.github.com/en/get-started/git-basics/about-remote-repositories). For example, cloning with HTTPS URL is done as follows:
37+
```
38+
git clone https://github.com/mesh-adaptation/<PACKAGE>.git
39+
```
40+
41+
Once cloned, the package can be [installed using pip](https://pip.pypa.io/en/stable/topics/local-project-installs/):
42+
```
43+
python3 -m pip install -e <PACKAGE>
44+
```
45+
46+
## Updating
47+
48+
It is highly recommended to keep your Firedrake installation and Mesh Adaptation software stack up to date.
49+
**We recommend updating the full stack at least once every two months.**
50+
51+
* To update Firedrake and PETSc, follow the [official Firedrake instructions](https://www.firedrakeproject.org/install.html#updating-firedrake) on how to do so.
52+
* To update Animate/Goalie/Movement, simply change directory to where each one is located (`cd /path/to/package`) and run `git pull`.
53+
1754
## Docker container approach
1855

19-
A bespoke Firedrake Docker image exists and can be downloaded and run as an alternative to the above:
56+
We provide a bespoke Docker image with PETSc, Firedrake, Animate, Goalie, and Movement already preinstalled.
57+
58+
The image can be downloaded and run as follows:
2059
```
2160
docker pull ghcr.io/mesh-adaptation/firedrake-parmmg:latest
2261
docker run -it ghcr.io/mesh-adaptation/firedrake-parmmg:latest
2362
```
2463

2564
For more information on how to run docker containers, see the [official documentation](https://docs.docker.com/engine/containers/run/). For example, since all data inside a container is only accessible from inside the container, it is useful to create [filesystem mounts](https://docs.docker.com/engine/containers/run/#filesystem-mounts) to be able to access data from outside the container.
2665

27-
2866
### Using GPUs inside a container
2967

3068
Passing the `--gpus` flag to `docker run` allows us to use GPUs inside containers (see [Docker documentation](https://docs.docker.com/reference/cli/docker/container/run/#gpus) for details). For example, to use all available GPUs, run the following:
@@ -51,36 +89,3 @@ Now you may proceed with installing GPU-supported software as normal. For exampl
5189
```
5290
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
5391
```
54-
55-
## Installing Mesh Adaptation modules
56-
57-
The Mesh Adaptation packages can be installed through the following options, denoting the package of interest by `<PACKAGE>`.
58-
In both cases, make sure that you have activated the Python virtual environment that was created when you installed Firedrake.
59-
Ensure that you have activated the Python virtual environment associated with your Firedrake installation before following the steps below:
60-
```
61-
source /path/to/venv/bin/activate
62-
```
63-
64-
### Cloning via HTTPS
65-
66-
```
67-
git clone https://github.com/mesh-adaptation/<PACKAGE>.git
68-
cd <PACKAGE>
69-
make install
70-
```
71-
72-
### Cloning via SSH
73-
74-
```
75-
git@github.com:mesh-adaptation/<PACKAGE>.git
76-
cd <PACKAGE>
77-
make install
78-
```
79-
80-
## Updating
81-
82-
It is highly recommended to keep your Firedrake installation and Mesh Adaptation software stack up to date.
83-
**We recommend updating the full stack at least once every two months.**
84-
85-
* To update Firedrake and PETSc, follow the [official Firedrake instructions](https://www.firedrakeproject.org/install.html#updating-firedrake) on how to do so.
86-
* To update Animate/Goalie/Movement, simply change directory to where each one is located (`cd /path/to/package`) and run `git pull`.

0 commit comments

Comments
 (0)