Command-Line Interface (CLI)

After installing the package (pip install -e .), the ggp command is available in your Conda environment.

ggp --help
ggp --version

Command Overview

The CLI provides two top-level commands: optimize and info.

info Command

Displays what is available in the current installation.

ggp info                  # show everything
ggp info --presets        # list built-in problem presets
ggp info --mappers        # list registered projection mappers
ggp info --backends       # list available linear-algebra backends

optimize Command

Runs an end-to-end topology optimisation from a built-in preset or a custom YAML file.

ggp optimize --preset <name>   [OPTIONS]
ggp optimize --config <file>   [OPTIONS]

You must provide exactly one of --preset or --config.

Source options:

  • --preset <name> — use a built-in preset YAML (see ggp info --presets). Built-in presets: short_cantilever, mbb, l_shape, alm_cantilever.

  • --config <path> — path to a custom YAML problem definition file.

Override options (applied on top of the preset or config file):

  • --max-iter <int> — maximum number of outer optimisation iterations.

  • --algorithm <str> — optimisation algorithm: MMA, SLP, or CONLIN.

  • --volfrac <float> — target volume fraction constraint.

  • --fem-solver <backend> — FEM linear-system backend. Choices:

    • direct (default) — scipy.sparse.linalg.spsolve (SuperLU/UMFPACK); best for small-to-medium 2-D meshes.

    • iterative — PETSc CG + GAMG; recommended for large 3-D meshes.

    • amjax — AMG-preconditioned CG (PyAMG smoothed-aggregation hierarchy used as a preconditioner for scipy.sparse.linalg.cg); implements the core approach of the AMJax library. Suitable for both 2-D and 3-D problems. Requires pyamg (installed via environment.yml).

  • --iterative — shorthand flag equivalent to --fem-solver iterative. Kept for backward compatibility.

  • --use-line-search — flag: enable monotone backtracking line search. Recommended with SLP or CONLIN.

Examples

Run the short cantilever benchmark with default settings:

ggp optimize --preset short_cantilever

Run the MBB beam with SLP and line search:

ggp optimize --preset mbb --algorithm SLP --use-line-search

Run the ALM cantilever with 30 iterations:

ggp optimize --preset alm_cantilever --max-iter 30

Override the volume fraction on any preset:

ggp optimize --preset l_shape --volfrac 0.3 --algorithm CONLIN

Run from a custom YAML file with the iterative solver:

ggp optimize --config my_3d_problem.yaml --iterative --max-iter 50

Run the short cantilever with the AMJax JAX-accelerated solver:

ggp optimize --preset short_cantilever --fem-solver amjax

Run a 3-D problem with AMJax (GPU-compatible, JIT-compiled):

ggp optimize --config my_3d_problem.yaml --fem-solver amjax --max-iter 50

YAML Problem Definition Format

Custom YAML files follow the ProblemSpec schema. The minimal structure is:

geometries:
  - type: fenics_rectangle
    role: design
    params:
      Lx: 60.0
      Ly: 30.0
      nx: 60
      ny: 30

boundary_conditions:
  - region: left
    type: fixed

loads:
  - region: mid_right
    type: point
    value: [0.0, -1.0]

formulation:
  mode: Free          # Free | 2D_Free | ALM | 2D_ALM | 3D_Free | 3D_ALM
  num_components: 18

solver:
  algorithm: MMA      # MMA | SLP | CONLIN
  max_iter: 50
  fem_solver: amjax   # direct | iterative | amjax (built-in presets default to amjax)

volfrac: 0.4

For a 3-D problem, use type: fenics_box with params Lx, Ly, Lz, nx, ny, nz, set formulation.mode to 3D_Free or 3D_ALM, and set solver.fem_solver to iterative or amjax in the YAML (or pass the equivalent CLI flag).

The built-in presets in ggp/cli/presets/ serve as ready-to-copy starting points.