Running PIPS-IPM++

Executing gmspips

The actual PIPS-IPM++ executable is gmspips. Consult PIPS-IPM++ Input: Format and Generation in order to learn on how to annotate models in GAMS and how to split them into multiple files so that PIPS-IPM++ can handle them.

Assuming one already has split a model instance in SOMEFOLDER with files named model0.gdx, model1.gdx, ..., modelN.gdx, where N is the number of blocks in your problem, a typical call to PIPS-IPM++ running on n processes to solve the model looks like:

mpirun -np n /path/to/gmspips N+1 SOMEFOLDER/model

Note that the actual MPI command mpirun might differ depending on your system and MPI installation (it could be srun etc.). One can also run PIPS-IPM++ sequentially (leaving out the mpirun -np n part), but that would somehow defeat its purpose.

The number of threads used by each MPI process in PIPS-IPM++ can be controlled by setting the environment variable OMP_NUM_THREADS. PIPS-IPM++ will complain if this variable is not set. Best performance (from our point of view) can currently be achieved by setting:

export OMP_NUM_THREADS=2

However, a value of 1 is also fine and generally performance will depend on the instance.

Option files

Upon starting, PIPS-IPM++ will look for an options file called PIPSIPMpp.opt in the current working directory and read in its options. Each line has the following structure:

PARAMETERNAME VALUE

where PARAMETERNAME is the name of the parameter to set and VALUE the value to set it to.

The interested user can find numerous parameters and short descriptions in Available Options, but expert knowledge of PIPS-IPM++ is currently required here and if in doubt, one should contact the developers (until a concise guide is available).

We recommend setting the following options:

SCALER geometricmean
IP_METHOD primal-dual

These enable geometric mean scaling and the use of primal and dual step lengths in the interior-point method.

Options can also be set on the command line by using argument --PARAMETERNAME=VALUE.

Available Options

Output

Name	Default	Range	Type	Description
FILTER_VERBOSE	false		boolean	whether to be verbose in Filter strategy
LINEARSOLVER_LEAF_VERBOSE	0	≥ 0	integer	log verbosity level for linear solver for leaf system
LINEARSOLVER_ROOT_VERBOSE	0	≥ 0	integer	log verbosity level for linear solver for root system
OUTER_BICG_PRINT_STATISTICS	false		boolean	whether to print BiCGStab statistics (system and residual norms)
PRESOLVE_PRINT_PROBLEM	false		boolean	whether to write the problem to stdout before and after presolve
PRESOLVE_VERBOSITY	1	≥ 0	integer	verbosity of log output of presolve
PRINT_TREESIZES_ON_READ	false		boolean	whether to print matrix sizes when initializing problem
REGULARIZATION_VERBOSE	false		boolean	whether to enable verbose output of regularization
SCALER_OUTPUT	true		boolean	whether scaler should print ratios after scaling
SILENT	false		boolean	whether to suppress some output in DistributedTreeCallbacks
XYZS_SOLVE_PRINT_RESISDUAL	false		boolean	whether to print residuals in XYZS solve

Presolve

Name	Default	Range	Type	Description
PRESOLVE	true		boolean	whether to apply presolve
PRESOLVE_ABORTFRAC	0.0005		real	required row/column reductions as a fraction of rows/columns to start another presolving round
PRESOLVE_AGGREGATION	true		boolean	whether to enable the aggregation presolver
PRESOLVE_BOUND_STRENGTHENING	true		boolean	whether to enable the bound strengthening presolver
PRESOLVE_BOUND_STR_MAX_ITER	2	≥ 0	integer	maximal number of bound strengthening rounds per presolve round
PRESOLVE_BOUND_STR_MAX_PARTIAL_ACTIVITY	1.79769e+308	≥ 0	real	maximal partial activity to be divided to derive a bound
PRESOLVE_BOUND_STR_NUMERIC_LIMIT_BOUNDS	1e+12	≥ 1	real	maximum absolute value of newly found bound in block matrix to be accepted by bounds strengthening presolver
PRESOLVE_BOUND_STR_NUMERIC_LIMIT_ENTRY	1e-07	≥ 0	real	minimal entry to divide by in order to derive a bound
PRESOLVE_COLUMN_FIXATION	true		boolean	whether to enable the column fixation presolver
PRESOLVE_COLUMN_FIXATION_MAX_FIXING_IMPACT	1e-12	≥ 0	real	maximal impact column fixing can have on the problem (currently ub-lb)
PRESOLVE_DUAL_TIGHTENING	true		boolean	whether to enable the dual bound tightening presolver
PRESOLVE_INFINITY	∞		real	value for infinity in presolvers
PRESOLVE_LINEAR_DEPENDENCIES	true		boolean	whether to enable the linear dependencies presolver
PRESOLVE_MAX_BOUND_ACCEPTED	1e+10	≥ 1	real	maximal absolute value of newly found bound to be propagated on the row by bounds strengthening presolver
PRESOLVE_MAX_ROUNDS	50	≥ 0	integer	maximal number of rounds to apply all presolvers
PRESOLVE_MODEL_CLEANUP_MATRIX_ENTRY_IMPACT_FEASDIST	0.01	≥ 0	real	maximal fraction between absolute value of matrix entry, multiplied by corresponding variables domain width and number of nonzeros in row, and feastol to remove the matrix entry due to having a low impact
PRESOLVE_MODEL_CLEANUP_MAX_MATRIX_ENTRY_IMPACT	0.001	≥ 0	real	maximal absolute value of a matrix entry that is removed from the problem due to having low impact
PRESOLVE_MODEL_CLEANUP_MIN_MATRIX_ENTRY	1e-10	≥ 0	real	maximal absolute value of a matrix entry that is removed from the problem
PRESOLVE_PARALLEL_COLUMNS	true		boolean	whether to enable the parallel columns presolver
PRESOLVE_PARALLEL_COLUMNS_TOL_COMPARE_ENTRIES	1e-08	≥ 0	real	tolerance for considering entries in two different columns to be equal
PRESOLVE_PARALLEL_ROWS	true		boolean	whether to enable the parallel rows presolver
PRESOLVE_PARALLEL_ROWS_TOL_COMPARE_ENTRIES	1e-08	≥ 0	real	tolerance for considering entries in two different rows to be equal
PRESOLVE_PERMUTATION	true		boolean	whether to enable the permutation presolver
PRESOLVE_RESET_FREE_VARIABLES	false		boolean	whether to reset free variables' bounds after presolve (given the row implying these bounds was not removed)
PRESOLVE_SINGLETON_COLUMNS	true		boolean	whether to enable the singleton columns presolver
PRESOLVE_SINGLETON_COLUMNS_MAX_ROUNDS	2	≥ 0	integer	maximum removal rounds in the singleton column presolver
PRESOLVE_SINGLETON_ROWS	true		boolean	whether to enable the singleton rows presolver
PRESOLVE_SINGLETON_ROWS_MAX_ROUNDS	2	≥ 0	integer	maximum removal rounds in the singleton row presolver
PRESOLVE_TRACK_COL	false		boolean	whether to track a column through presolve
PRESOLVE_TRACK_COL_INDEX	-1		integer	the index of the column to track
PRESOLVE_TRACK_COL_NODE	-1		integer	the node of the column to track
PRESOLVE_TRACK_ROW	false		boolean	whether to track a row through presolve
PRESOLVE_TRACK_ROW_INDEX	-1		integer	the index of the row to track
PRESOLVE_TRACK_ROW_LINKING	false		boolean	whether the row to track is in the linking part
PRESOLVE_TRACK_ROW_NODE	-1		integer	the node of the row to track
PRESOLVE_TRACK_ROW_SYSTEM	equalities	equalities, inequalities	string	the system of the row; equalities: equality system; inequalities: inequality system
PRESOLVE_TRANSFROM_INEQUALITIES_INTO_EQUALITIES	false		boolean	whether to transform inequalities into equalities at the end of presolve
STOP_AFTER_PRESOLVE	false		boolean	whether to abort PIPS after presolve

Postsolve

Name	Default	Range	Type	Description
POSTSOLVE	true		boolean	whether to apply postsolve
POSTSOLVE_PRINT_RESIDS	true		boolean	whether to print the residuals before and after unscaling and before and after postsolve
POSTSOLVE_TOLERANCE	0.0001	≥ 0	real	tolerance used for checking residuals after postsolve

Scaling

Name	Default	Range	Type	Description
SCALER	none	none, equilibrium, geometricmean, geometricequ, curtisreid	string	type of scaler to use; none: No scaling; equilibrium: Equilibrium scaling; geometricmean: Geometric Mean scaling; geometricequ: Geometric Mean and Equlibrium scaling; curtisreid: Curtis Reid scaling

Interior-Point Method

Name	Default	Range	Type	Description
IPM_MAX_ITER	300	≥ 0	integer	iteration limit for interior point method
IPM_PRINT_LINEAR_SYSTEM_DIAGONAL_STATISTICS	false		boolean	whether to print statistics on diagonal of linear system
IPM_TIMELIMIT	-1	≥ -1	real	time limit in seconds for interior point method, or -1 for no limit
IP_ACCURACY_REDUCED	false		boolean	whether to use reduced termination tolerance (mu and residual) for interior point method
IP_METHOD	primal	primal, primal-dual	string	interior point method to use; primal: primal method; primal-dual: primal-dual method
IP_PRINT_TIMESTAMP	true		boolean	whether to print timestamp when reporting interior point status
IP_STEPLENGTH_CONSERVATIVE	false		boolean	whether to use a more conservative steplength heuristic (smaller steplength_factor and gamma_f)

Regularization

Name	Default	Range	Type	Description
FRIEDLANDER_ORBAN_REGULARIZATION_DUAL_MIN	1e-10	≥ 0	real	minimal FriedlanderOrban regularization for dual part
FRIEDLANDER_ORBAN_REGULARIZATION_INITIAL_DUAL_Y	1	≥ 0	real	initial FriedlanderOrban regularization for dual equalities part
FRIEDLANDER_ORBAN_REGULARIZATION_INITIAL_DUAL_Z	1	≥ 0	real	initial FriedlanderOrban regularization for dual inequalities part
FRIEDLANDER_ORBAN_REGULARIZATION_INITIAL_PRIMAL	1	≥ 0	real	initial FriedlanderOrban regularization for primal part
FRIEDLANDER_ORBAN_REGULARIZATION_PRIMAL_MIN	1e-10	≥ 0	real	minimal FriedlanderOrban regularization for primal part
IPOPT_REGULARIZATION_MAX_PRIMAL	1e+40	≥ 1	real	maximal Ipopt regularization
IPOPT_REGULARIZATION_MIN_PRIMAL	1e-20	≥ 0	real	minimal Ipopt regularization
REGULARIZATION	false		boolean	whether to apply regularization to the linear system
REGULARIZATION_STRATEGY	friedlander	ipopt, friedlander	string	regularization strategy; ipopt: Ipopt's strategy; friedlander: strategy of Friedlander and Orban

Schur Complement

Name	Default	Range	Type	Description
ALLREDUCE_SCHUR_COMPLEMENT	false		boolean	whether the Schur-Complement should be allreduced to all processes instead of only a single one
PARDISO_PRECONDITION_SPARSE	false		boolean	whether to use sparse Preconditioner in Pardiso indefinite solver
PRECONDITION_SPARSIFY	false		boolean	whether to use distributed sparsification Preconditioner
PRECONDITION_SPARSIFY_FAKE	false		boolean	whether to run distributed Schur complement computation but also deactivate the distributed preconditioner (for debugging only)
SCHUR_COMPLEMENT_FORCE_SPARSE_COMPUTATIONS	false		boolean	whether to force sparse computations for Schur-Complement
SC_BLOCKWISE_BLOCKSIZE_MAX	20	≥ 0	integer	maximal blocksize in blockwise Schur-Complement
SC_COMPUTE_BLOCKWISE	false		boolean	whether to use block-wise Schur-Complement computation
SC_ELIMINATE_C0	true		boolean	whether to eliminate C from the Schur complement

Outer Solve

Name	Default	Range	Type	Description
OUTER_BICG_DYNAMIC_TOL	true		boolean	whether to choose BiCGStab tolerance dynamically (according to iteration number)
OUTER_BICG_EPSILON	1e-15	≥ 0	real	minimal convergence tolerance for BiCGStab
OUTER_BICG_MAX_ITER	75	≥ 0	integer	limit on BiCGStab iterations
OUTER_BICG_MAX_NORMR_DIVERGENCES	4	≥ 0	integer	number of consecutive BiCGStab iterations without improvement in residual norm; BiCGStab stops with DIVERGED status if this is reached
OUTER_BICG_MAX_STAGNATIONS	4	≥ 0	integer	number of consecutive BiCGStab iterations with tiny step length (determined by OUTER_BICG_EPSILON); BiCGStab stops with STAGNATION status if this is reached
OUTER_BICG_TOL	1e-10	≥ 0	real	BiCGStab tolerance if OUTER_BICG_DYNAMIC_TOL is disabled
OUTER_SOLVE	bicgstab	none, iterref, bicgstab	string	controls the type of error absorption at the outer level of the linear system; none: no error absorption (OOQP works just fine); iterref: iterative refinement (used when error absorption is also done at a lower level, for example in the solve with the dense Schur complement); bicgstab: BiCGStab with the factorization as preconditioner
OUTER_SOLVE_REFINE_ORIGINAL_SYSTEM	false		boolean	whether to compute residuals for the original instead of the regularized system for refinement at the outer level

Inner Solve

Name	Default	Range	Type	Description
INNER_SC_SOLVE	none	none, iterref, bicgstab	string	controls the type of error absorption/correction at the inner level when solving with the dense Schur complement; currently must be left at none (#51); none: no error correction; iterref: iterative refinement; bicgstab: BiCGStab

Linear Solver

Name	Default	Range	Type	Description
LINEAR_DENSE_SOLVER	indefinite	indefinite, saddle, psd	string	solver for dense linear systems; indefinite: solver for symmetric indefinite systems; saddle: specialized LDL^T solver for saddle point systems; psd: solver for symmetric positive-definite systems
LINEAR_LEAF_SOLVER	ma57	ma57, ma27	string	solver for linear systems in leafs; ma57: HSL MA57; ma27: HSL MA27
LINEAR_ROOT_SOLVER	ma57	ma57, ma27	string	solver for linear system in root; ma57: HSL MA57; ma27: HSL MA27
LINEAR_SUB_ROOT_SOLVER	ma57	ma57, ma27	string	solver for linear system in sub-root; ma57: HSL MA57; ma27: HSL MA27
PARDISO_FOR_GLOBAL_SC	true		boolean	whether to use PARDISO to exploit the linking structure of the global Schur-Complement
PARDISO_NITERATIVE_REFINS	-1	≥ -1	integer	number of iterative refinements (PARDISO iparm[7]); -1 for automatic choice (currently 8)
PARDISO_NITERATIVE_REFINS_ROOT	-1	≥ -1	integer	number of iterative refinements for root system (PARDISO iparm[7]); -1 for automatic choice (currently 8)
PARDISO_PIVOT_PERTURBATION	-1	≥ -1	integer	exponent x for pivot perturbation 10^{-x} * |A|_inf (PARDISO iparm[9]); -1 for automatic choice (currently 8)
PARDISO_PIVOT_PERTURBATION_ROOT	-1	≥ -1	integer	exponent x for pivot perturbation 10^{-x} * |A|_inf for root system (PARDISO iparm[9]); -1 for automatic choice (currently 8)
PARDISO_SPARSE_RHS_LEAF	false		boolean	whether to pass RHS in sparse form to PARDISO for leaf solves
PARDISO_SYMB_INTERVAL	-1	≥ -1	integer	trigger PARDISO symbolic analysis any so many iterations; -1 for automatic choice (currently 8)

Line Search

Name	Default	Range	Type	Description
GONDZIO_MAX_CORRECTORS	3	≥ 0	integer	limit on number of computed Gondzio correctors
GONDZIO_STOCH_ADAPTIVE_LINESEARCH	true		boolean	whether adaptive linesearch should be applied in the GondzioStoch solvers
GONDZIO_STOCH_ADDITIONAL_CORRECTORS_MAX	1	≥ 0	integer	maximal number of additional corrector steps to apply (in addition to the still existing gondzio corrector limit)
GONDZIO_STOCH_ADDITIONAL_CORRECTORS_SMALL_VARS	true		boolean	whether to apply additional corrector steps for small complementarity pairs
GONDZIO_STOCH_FIRST_ITER_SMALL_CORRECTORS	10	≥ 0	integer	first iteration at which to look for small corrector steps
GONDZIO_STOCH_FREQUENCY_PUSH_CONVERGED_VARS	4	≥ 0	integer	frequency by which converged variables should be pushed away from their bounds
GONDZIO_STOCH_MAX_ALPHA_SMALL_CORRECTORS	0.95	≥ 0	real	maximal alpha for the IPM to try and apply small corrector steps
GONDZIO_STOCH_MU_LIMIT_PUSH_CONVERGED_VARS	0.001	≥ 0	real	from which value of mu on should converged variables be pushed away from their bounds
GONDZIO_STOCH_N_LINESEARCH	10	≥ 0	integer	number of linesearch points if GONDZIO adaptive linesearch is enabled
GONDZIO_STOCH_PUSH_CONVERGED_VARS_FROM_BOUND	false		boolean	whether to push relatively early converged variables away from their bounds artificially
GONDZIO_STOCH_USE_DYNAMIC_CORRECTOR_SCHEDULE	false		boolean	whether to schedule the amount of Gondzio correctors dynamically; invalidates the max correctors setting

Hierarchical Approach

Name	Default	Range	Type	Description
HIERARCHICAL	false		boolean	whether to use the hierarchical approach
HIERARCHICAL_APPLY_SPLIT	true		boolean	whether to apply splits in the hierarchical approach
HIERARCHICAL_APPROACH_N_LAYERS	2	≥ 1	integer	number of layers in hierarchical approach; 1: only dense border, 2: dense border + 1 additional layer, ...
HIERARCHICAL_FORCE_N_SUBROOTS	-1	≥ -1	integer	force a number of subroots for the hierarchical approach instead of the automatic detection; do not use
HIERARCHICAL_MOVE_A0_TO_DENSE_LAYER	false		boolean	whether to move matrix A0 to the dense layer in the hierarchical approach
HIERARCHICAL_PRINT_HIER_DATA	false		boolean	whether to print hierarchical approach problem data
HIERARCHICAL_TESTING	false		boolean	whether to activate some debugging of the hierarchical approach
SC_BLOCKSIZE_HIERARCHICAL	20	≥ 0	integer	columns to solve for at once when computing the hierarchical Schur-Complements
SC_HIERARCHICAL_COMPUTE_BLOCKWISE	true		boolean	whether all columns should be computed at once when computing the hierarchical Schur-Complements

Miscellaneous

Name	Default	Range	Type	Description
WRITE_ORIGINAL_PROBLEM_TO_LP	""		string	name of file to which to write original problem in LP format (requires one MPI process)
WRITE_PRESOLVED_PROBLEM_TO_LP	""		string	name of file to which to write presolved problem in LP format (requires one MPI process and presolve enabled)