Installation Guide

This guide provides a detailed, step-by-step walk-through to reproduce the exact environment required to run the ggp framework.

System Requirements

Topology optimization frameworks rely on robust C++ libraries for finite element analysis. The framework uses FEniCS 2019.1.0.

Warning

FEniCS requires a UNIX-like environment. Windows users MUST use Windows Subsystem for Linux (WSL2) or Docker. Native Windows installations of FEniCS are not supported.

Step 1: Install Conda

If you do not have Conda installed, we recommend installing Miniconda inside your Linux/WSL terminal:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

Restart your terminal after installation.

Step 2: Clone the Repository

Clone the repository to your local machine and navigate into it:

git clone https://github.com/SimoneConiglio/generalized_geometry_projection.git
cd generalized_geometry_projection

Step 3: Create the Conda Environment

We provide an environment.yml file that strictly pins the FEniCS version alongside GEMSEO and all required scientific tools (NumPy, SciPy, Jupyter, Sphinx). It also installs the optional AMJax FEM solver backend dependencies (pyamg, jax, jaxlib) via pip. These are only used when solver.fem_solver: amjax is selected; the default direct backend requires only SciPy.

Run the following command from the root of the cloned repository:

conda env create -f environment.yml

This process may take a few minutes as it downloads and resolves the FEniCS binaries from conda-forge.

Step 4: Activate the Environment

Every time you work on this project, you must activate the environment:

conda activate ggp

Step 5: Install the Package

Install the ggp package in editable mode so that the ggp CLI is available and Python can import the package without manual PYTHONPATH manipulation:

pip install -e .

This registers the ggp entry-point command and the ggp-topo package into the active Conda environment.

Step 6: Verify the Installation

You can verify that all dependencies and internal modules are working by running the provided pytest suite:

pytest tests/

You can also confirm the CLI is working:

ggp --version
ggp info --presets

If the tests pass and the CLI responds, you are ready to run the examples or develop your own topology optimization workflows.