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.
OpenSEFA.PresolveModule.MixConfig — Type
Use RREF for linear dependency reduction depending on sparsity pattern.
OpenSEFA.PresolveModule.PresolveConfig — Type
For now only refers to the linear dependency solver.
OpenSEFA.PresolveModule.PresolveConfig — Method
Default presolve config.
OpenSEFA.PresolveModule.PresolvedReconciliationProblem — Type
Struct holding the problem after the symbolic/numeric presolve pipeline.
OpenSEFA.PresolveModule.QRConfig — Type
Config using QR for linear dependency reduction.
OpenSEFA.PresolveModule.RREFConfig — Type
Config using RREF for linear dependency reduction.
OpenSEFA.PresolveModule.RedundancyData — Type
Data structure holding the result of redundant equations removal.
OpenSEFA.PresolveModule.SparseRREFConfig — Type
Config using sparse RREF for linear dependency reduction.
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.
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.
OpenSEFA.PresolveModule.check_replacements! — Method
Check if new replacements from trivial replacements are valid.
OpenSEFA.PresolveModule.check_replacements! — Method
Check if new replacements from bilinear replacements are valid.
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.
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.
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.
OpenSEFA.PresolveModule.find_unobservable_variables_in_constraints! — Method
Find free measured and unmeasured variables from the constraint equations for a ReconciliationSolution around a computed solution values.
OpenSEFA.PresolveModule.independent_cols! — Method
Return vector of pivots and nullspace of a matrix
OpenSEFA.PresolveModule.independent_cols_qr — Method
Return vector of pivots with a QR based algorithm
OpenSEFA.PresolveModule.independent_cols_qr — Method
Sparse QR-based method for selecting independent columns.
OpenSEFA.PresolveModule.presolve! — Method
In-place presolve.
OpenSEFA.PresolveModule.presolve — Method
Apply presolve scheme.
OpenSEFA.PresolveModule.remove_fixed_variables! — Method
Remove fixed variables replacing by their corresponding values.
OpenSEFA.PresolveModule.remove_measured_variables! — Method
Each measured variable is replaced by its corresponding mean value and removed from the problem. The result is an equivalent problem without measured variables.
OpenSEFA.PresolveModule.remove_redundant_equations! — Method
Remove redundant equations using the RREF algorithm.
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.
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.
OpenSEFA.PresolveModule.scale_columns! — Method
Scale in-place the columns of the matrix by the maximum absolute among rows. Returns the vector of scale factors applied to each column.
OpenSEFA.PresolveModule.trivial_and_bilinear_substitutions_recursive! — Function
Recursively perform trivial and product substitions until no more are found.
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.
OpenSEFA.PresolveModule.trivial_substitutions_recursive! — Method
Recursively perform trivial substitions until no more are found.
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.