Presolve module

OpenSEFA.PresolveModule — Module

Transformations that simplify a reconciliation problem before optimization.

The presolver applies a sequence of structure-exploiting steps:

  • Trivial substitutions: solve for variables that appear in single-variable equations.
  • Bilinear substitutions: propagate known transfer coefficients into adjacent equations.
  • Fixed variable removal: substitute fixed values into all equations.
  • Redundant equation removal: detect and drop linearly dependent equations using RREF or QR.
  • Unobservable variable detection: identify unmeasured variables not uniquely determined by the system.

The result is a PresolvedReconciliationProblem containing a smaller equivalent reduced problem plus a dictionary of already-determined variable assignments.

source
OpenSEFA.PresolveModule.augmented_matrix — Method

Construct the augmented matrix [A|b] for a linear reconciliation problem.

The augmented matrix combines the coefficient matrix A with the constant terms vector b, forming the standard representation of a linear system Ax = b. Variables respect the following order: measured, unmeasured, fixed.

This method is useful for debugging. If the system is not linear an error is returned.

source
OpenSEFA.PresolveModule.bilinear_substitutions! — Function

A bilinear substitution is applied on terms of the form c - v * w = 0 where c is a constant and v and w are a variables. In other equations, v * w or w * v is replaced by c.

If we can solve for v * w or w * v in two or more equations, this is considered a valid substition only if the found values match within rtol relative tolerance.

source
OpenSEFA.PresolveModule.check_variables — Method

Debug consistency check: verifies that the set of variables in 'rec' matches exactly the set of variables referenced across all equations. Used after equation removal to detect variables that have become orphaned.

source
OpenSEFA.PresolveModule.equations_matrix — Method

Create matrix A (rows = variables, columns = equations) and constant terms vector c. Bilinear terms are lifted to a new independent variable. linear_term_idx maps variable labels to 1-based row indices in A. bilinear_term_idx maps variable-pair labels to row indices in A continuing after the linear rows.

source
OpenSEFA.PresolveModule.find_unobservable_variables_in_constraints! — Function

Find unobservable measured and unmeasured variables from the constraint equations for a ReconciliationProblem around a given point evaluation_values. The idea is to linearize the constraints of the ReconciliationProblem around the given values (i.e., compute the jacobian) and check the linearized system for not uniquely solvable variables using the rref algorithm. This method runs more stable if the ReconciliationProblem has been presolved before.

source
OpenSEFA.PresolveModule.replace_bilinear_terms! — Function

Each given product v * w is replaced by its corresponding constant value and removed from the problem. The result is an equivalent problem without those product terms provided that one equation defining the product value is kept (to be specified in storing_equations). The method does not check for w * v!

Important: The variables dictionary cannot be alised to any of rec's dictionaries.

Algorithm

For each variable we loop through each equation, making the replacements:

  • Bilinear terms with matching product (permutations are not considered!) are replaced to constant terms.

For the tolerance for the consistency check of equations (left-hand side is zero) during variable removal see ComparisonModule.

source
OpenSEFA.PresolveModule.replace_variables! — Method

Each given variable is replaced by its corresponding constant value and removed from the problem. The result is an equivalent problem without those variables.

Important: The variables dictionary cannot be alised to any of rec's dictionaries.

Algorithm

For each variable we loop through each equation, making the replacements:

  • Linear terms with matching name are replaced with constants.
  • Bilinear terms with matching name are replaced to linear terms.

For the tolerance for the consistency check of equations (left-hand side is zero) during variable removal see ComparisonModule.

source
OpenSEFA.PresolveModule.trivial_substitutions! — Method

A trivial substitution is applied on terms of the form c - v = 0 or c + v² = 0 where c is a constant and v is a variable.

For squared terms, the substitution is only done if the variable bounds uniquely determine the solution, i.e. one of sqrt(c) and -sqrt(c) is not within the variable bounds or they match within rol relative tolerance.

If we can solve for v in two or more equations, this is considered a valid substition only if the found values match within rol relative tolerance.

source
OpenSEFA.PresolveModule.update_unobservable_vars! — Function

Check for variables in 'varstocheck' if they don't participate in any equation of the PresolvedReconciliationProblem 'prerec'. If so, declare it as 'unobservable' and remove it from 'rec'. If 'varstocheck' is not specified (i.e., 'nothing'), check all variables from the ReconciliationProblem.

source