PIPS-IPM++ Solver and Tools
a parallel interior-point method for doubly bordered block diagonal linear programs
The PIPS-IPM++ Docker Image

A Docker image for PIPS-IPM++ is available in the container registry registry.gitlab.com/pips-ipmpp/pips-ipmpp. Based on debian:stable, it includes a pre-built version of PIPS-IPM++ located in /pips-ipmpp/build and a Python-based controller to orchestrate complex decomposition workflows. The build specifically utilizes the MUMPS linear system solver.

The PIPS-IPM++ Docker image provides a specialized environment for annotating, splitting, and solving large-scale linear programming instances. The container offers users two primary interfaces: a command-line interface (CLI) for direct automation and a stateful interactive shell for step-by-step session management.

Starting the Container

To use the PIPS-IPM++ Docker container effectively, you must mount a local directory to the container so that the application can access your problem files and save results.

  1. Create a Working Directory: On your host machine, create a directory (e.g., /path/to/workdir) and place your instance files (.mps, .dec, or .gdx) there.
  2. Options Files: If specific solver options are required, place a file named PIPSIPMpp.opt in this directory.
  3. Run Command: Use the -v flag to mount your local path to /workdir inside the container and the -w flag to set it as the active working directory.

Basic Syntax:

docker run -v /path/to/workdir:/workdir -w /workdir -it pips-ipmpp [command]

Without a command, the container defaults to starting the Interactive Shell. The available commands are interactive and cli.

Key Features

The CLI and interactive shell of the image both provide three primary features to manage the PIPS-IPM++ pipeline:

  • Annotate: Generates an annotated GDX file required for decomposition. It supports manual block definition via a .dec file (using GAMS mps2gms) or automatic block detection via pipstools.
  • Split: Partitions an annotated GDX file into individual block files using the gmschk utility, which is necessary for parallel solving. The split command generates a separate GDX file for each block.
  • Solve: Orchestrates the solution process using gmspips. It can handle individual stages or an automated "full pipeline" that handles annotation and splitting in one step.

Input types

Three different input types are accepted by the container: MPS (and MPS.GZ), GDX and a file stem. In order for PIPS-IPM++ to read the instance, it must have a block structure annotation. The annotation can be performed automatically or, in the case of an MPS file, given by supplying a DEC file. An annotated GDX file can be solved directly using PIPS-IPM++. All annotated GDX files can be split into separate GDX files per block. When solving the split problem, the solve command must be supplied the file stem.

Interactive Shell

The interactive shell provides a stateful environment that remembers your loaded files and block counts across commands.

Launch:

docker run -v /path/to/workdir:/workdir -w /workdir -it pips-ipmpp interactive

Shell Commands

  • read <file> [dec_file]: Loads your primary problem file (.mps, .mps.gz, or .gdx) and an optional decomposition file (.dec).
  • blocks <num>: Manually sets or overrides the number of blocks for the session.
  • annotate [args]: Annotates the loaded file. If a .dec is present, it uses GAMS; otherwise, it calls pipstools.
  • split [--blocks <num>]: Partitions the file into the specified number of blocks.
  • solve [options]: Solves the problem. It automatically uses the session's current file, block count, and .dec file unless overridden.

Quick Shell Examples

Action Interactive Shell Commands
Annotate a GDX with 10 blocks read prob.gdx → blocks 10 → annotate
Split a GDX with 10 blocks read prob.gdx → blocks 10 → split
Solve a GDX with 10 blocks read prob.gdx → blocks 10 → solve
Solve from a filestem (10 blocks) read prob_stem → solve --blocks 10
Annotate an MPS with 5 blocks read model.mps → annotate --blocks 5 (Result: model_5b.gdx)
Annotate using a DEC file read model.mps model.dec → annotate (Result: annotated GDX file)

Typical work flow

An instance is provided as an MPS file small.mps

(pips-ipm++) > read small.mps
Successfully read input file: /workdir/small.mps
(pips-ipm++) > blocks 2
(pips-ipm++) > annotate
Executing: cli annotate /workdir/small.mps --blocks 2
Annotation successful. Output: /workdir/small_2b.gdx, Scenarios: 2
(pips-ipm++) > solve
Executing: cli solve /workdir/small_2b.gdx --blocks 2

If a DEC file is available

(pips-ipm++) > read small.mps small.dec
Successfully read input file: /workdir/small.mps
Successfully read dec file: /workdir/small.dec
(pips-ipm++) > annotate
Executing: cli annotate /workdir/small.mps --dec-file /wordir/small.dec
Annotation successful. Output: /workdir/small_2b.gdx, Scenarios: 2
(pips-ipm++) > solve
Executing: cli solve /workdir/small_2b.gdx --blocks 2

Command Line Interface (CLI)

The CLI is designed for non-interactive automation and direct commands.

CLI Commands

  • cli annotate <file> [options]: Runs the annotation stage. All options are passed to pipstools.
  • cli split <gdx_file> --blocks <num>: Splits a GDX into num blocks.
  • cli solve <input> --blocks <num> [options]: The primary entry point for solving. All options are passed to gmspips.

CLI Examples

Action CLI Command
Annotate a GDX with 10 blocks cli annotate prob.gdx --blocks 10
Split a GDX with 10 blocks cli split prob_10b.gdx --blocks 10
Solve a GDX with 10 blocks cli solve prob_10b.gdx --blocks 10
Solve from a filestem (10 blocks) cli solve prob_stem --blocks 10
Annotate an MPS with 5 blocks cli annotate model.mps --blocks 5
Annotate an MPS using a DEC file cli annotate model.mps --dec-file model.dec

Comprehensive Solve Workflow

The solve command can automate different segments of the PIPS-IPM++ pipeline based on the input provided.

Input Type Command Variant Action Taken
Filestem cli solve stem --blocks 10 Directly solves pre-split GDX files (stem0.gdx...stem9.gdx).
GDX cli solve prob.gdx --blocks 10 Attempts to solve the unsplit GDX file.
GDX + Split cli solve prob.gdx --blocks 10 --split Forces a split step on the GDX before solving.
GDX + Full cli solve prob.gdx --blocks 10 --annotate --split Re-annotates, splits, and then solves.
MPS cli solve model.mps --blocks 10 Automatically performs annotate → split → solve.
MPS + DEC cli solve model.mps --dec-file model.dec Annotates via DEC file, then splits and solves.

Note: All commands above support the --mpi <n> flag for parallel execution and --hsl-lib <path> for HSL solvers.

Using HSL Linear Solvers

To use HSL solvers (e.g., MA57), you must provide a library named libcoinhsl.so. Mount the library and use the --hsl-lib flag:

docker run -v /path/to/hsl/lib:/libs -v /path/to/workdir:/workdir -w /workdir -it pips-ipmpp cli solve model.mps --blocks 10 --hsl-lib /libs

Required PIPSIPMpp.opt settings for MA57:

LINEAR_LEAF_SOLVER ma57
LINEAR_ROOT_SOLVER ma57
LINEAR_SUB_ROOT_SOLVER ma57

Using PIPS-IPM++ Directly

Advanced users can bypass the Python controller and call the PIPS-IPM++ binaries directly:

gmschk

docker run -v /path/to/workdir:/workdir -w /workdir pips-ipmpp gmschk 7 annot.gdx

gmspips

docker run -v /path/to/workdir:/workdir -w /workdir pips-ipmpp gmspips 7 annot.gdx

pipstools

Access pipstools directly for advanced annotation and model analysis: docker run pips-ipmpp pipstools --help