Core workflow

PEP()

Create an empty performance estimation problem and reset the global symbolic registries used to index points, expressions, functions, constraints, and PSD blocks.

A PEP stores the symbolic description of a worst-case analysis: function or operator classes, initial points, initial conditions, performance metrics, and optional PSD constraints. Calling solve! converts this symbolic description into a semidefinite program in JuMP.

Fields

• list_of_functions: function/operator classes declared in the problem.
• list_of_points: initial leaf points registered by set_initial_point!.
• list_of_conditions: scalar initial or normalization constraints.
• list_of_performance_metrics: expressions whose minimum is maximized.
• list_of_psd: global PSD constraints.
• residual: dual residual matrix associated with the Gram PSD constraint.

Mathematical model

PEPit computes the smallest valid worst-case constant by maximizing a performance expression over all symbolic iterates and oracle values satisfying the selected interpolation constraints and initial conditions.

Point(; is_leaf=true, decomposition_dict=nothing)

Represent an element of the ambient Hilbert space used by a performance estimation problem.

Point objects encode both iterates and gradients/subgradients. A leaf point is an independent symbolic vector and receives its own row/column in the Gram matrix. A non-leaf point stores a linear combination of leaf points through decomposition_dict; no new Gram coordinate is introduced.

Fields

• _id: unique object identifier used for hashing and equality.
• _is_leaf: whether the point is an independent symbolic vector.
• decomposition_dict: coefficients of the point in the leaf-point basis.
• counter: Gram-matrix index for leaf points, or nothing for non-leaves.
• _value: numerical vector recovered from the solved Gram matrix.

Mathematical model

If p and q are Points, then p + q, p - q, and scalar multiples are again symbolic points. The product p * q creates an Expression representing the inner product \langle p, q \rangle, and p^2 represents \|p\|^2.

Examples

x0 = Point()
x1 = Point()
direction = (x1 - x0) / 2
squared_norm = direction^2

See also Expression, PEP, set_initial_point!, and evaluate.

Expression(; is_leaf=true, decomposition_dict=nothing)

Represent a symbolic scalar expression in a PEP model.

An Expression is an affine combination of three kinds of scalar atoms: independent leaf function values, inner products of leaf Point objects, and constants. These expressions are used for function values, initial conditions, performance metrics, interpolation inequalities, and PSD matrix entries.

Fields

• _id: unique object identifier used for hashing and equality.
• _is_leaf: whether the expression is an independent scalar function value.
• decomposition_dict: coefficients keyed by leaf expressions, point pairs, or the constant key 1.
• counter: scalar-function-value index for leaf expressions, or nothing.
• _value: numerical scalar recovered after the PEP is solved.

Mathematical model

Products of points create expression atoms: if x and g are points, x * g represents \langle x, g \rangle. Scalar algebra on expressions builds affine combinations, and comparisons such as expr <= 0 create Constraint objects.

See also Point, Constraint, value!, and evaluate.

Constraint(expression, equality_or_inequality)

Represent a scalar equality or inequality constraint in a PEP.

The stored expression is the canonical left-hand side. Inequalities are stored in the form expression <= 0, while equalities are stored as expression == 0. Users normally create constraints through overloaded comparisons such as expr <= 1, expr1 >= expr2, or expr1 == expr2.

Fields

• expression: symbolic scalar residual.
• equality_or_inequality: either "equality" or "inequality".
• counter: global scalar-constraint index.
• _dual_variable_value: dual multiplier populated after solving.
• _value: numerical residual populated by evaluate.

Mathematical model

Scalar constraints encode initial conditions, performance metric epigraph constraints, function/operator interpolation inequalities, and auxiliary relations introduced by primitive steps.

See also Expression, add_constraint!, set_initial_condition!, and eval_dual.

PSDMatrix(matrix_of_expressions)

Represent a positive-semidefinite matrix constraint with symbolic entries.

A PSDMatrix stores a square matrix whose entries are Expression objects or real constants. It is used for interpolation conditions and additional matrix inequalities that are more naturally expressed as PSD blocks than as scalar inequalities.

Fields

• matrix_of_expressions: square matrix of symbolic scalar entries.
• shape: matrix dimensions.
• _value: numerical matrix value after solving.
• _dual_variable_value: PSD dual matrix after solving.
• entries_dual_variable_value: duals associated with entry-linking equalities in the JuMP model.
• counter: global PSD-constraint index.

See also add_psd_matrix!, evaluate, and eval_dual.

BlockPartition(d)

Represent a symbolic partition of points into d mutually orthogonal blocks.

Block partitions support block-coordinate interpolation constraints. Calling get_block on a point creates symbolic block components x^{(1)}, ..., x^{(d)} whose sum is the original point. The corresponding orthogonality constraints are generated later when the PEP is compiled.

Fields

• d: number of blocks.
• list_of_constraints: orthogonality constraints generated for this partition.
• blocks_dict: map from original points to their symbolic block components.
• counter: global partition index.

See also declare_block_partition!, get_block, and get_nb_blocks.

PEPFunction(; is_leaf=true, decomposition_dict=nothing, reuse_gradient=false)

Represent the internal symbolic function object shared by all concrete classes.

PEPFunction stores the data needed to model a leaf function, a leaf operator, or an affine combination of leaf objects. Concrete classes such as SmoothConvexFunction and MonotoneOperator wrap a PEPFunction and define their interpolation constraints by inspecting its registered oracle evaluations.

Fields

• _id: unique object identifier used for hashing and equality.
• _is_leaf: whether this object is a leaf function/operator.
• decomposition_dict: affine decomposition over leaf PEPFunction objects.
• reuse_gradient: whether repeated oracle calls at the same point reuse the same gradient/subgradient.
• list_of_points: registered triples (x, g, f) representing oracle calls.
• list_of_stationary_points: registered triples with zero gradient.
• list_of_constraints: scalar constraints attached to this function object.
• list_of_psd: user-added PSD constraints attached to this object.
• list_of_class_psd: class-generated PSD constraints.
• counter: leaf function index, or nothing for affine combinations.

Mathematical model

For a registered triple (x, g, f), the symbolic objects represent g \in \partial f(x) and the scalar value f(x) for the modeled class. During solve!, class-specific interpolation constraints relate all such triples.

See also declare_function!, oracle!, gradient!, value!, and add_constraint!.

DualPEPCertificate

Store the solution of the explicit conic dual generated by solve_dual!, including scalar multipliers, PSD multipliers, model handles, and solver statuses.

Fields

• dual_value: objective value of the explicit dual model.
• α: multipliers for performance-metric epigraph constraints.
• λ: multipliers for inequality initial/general conditions.
• ν: multipliers for equality initial/general conditions.
• θ: multipliers for scalar interpolation constraints.
• S: dual residual matrix for the main Gram PSD constraint.
• Y: PSD multipliers for global and class-generated PSD blocks.
• primal_model, dual_model: JuMP model handles.
• mappings: symbolic objects associated with the multiplier arrays.
• termination_status, primal_status, dual_status: solver statuses.

declare_function!(pep, func_class, param; reuse_gradient=nothing)

Declare a leaf function or operator class in pep and return the created object. param is typically an OrderedDict containing class parameters such as "L", "mu", or "beta".

Arguments

• pep::PEP: problem to which the class is added.
• func_class: concrete subtype of AbstractFunction.
• param: parameter dictionary consumed by func_class.
• reuse_gradient: optional override for repeated oracle evaluations at the same point.

Examples

problem = PEP()
f = declare_function!(problem, SmoothConvexFunction, OrderedDict("L" => 1.0))

declare_block_partition!(pep, d)

Create a BlockPartition with d blocks and register it for inclusion in the PEP model.

The returned partition is global to the current PEP construction context. Block orthogonality constraints are materialized during model construction.

set_initial_point!(pep)

Create and register a new leaf Point as an initial point of pep.

Initial points are independent vectors in the Gram matrix. They are typically used in initial conditions such as (x0 - xs)^2 <= R^2.

set_initial_condition!(pep, condition)

Add an initial condition or normalization constraint to pep.

Initial conditions define the admissible set of problem instances, for example \|x_0 - x_\star\|^2 \leq 1 or a bound on an initial function gap.

set_performance_metric!(pep, expression)

Register a scalar performance metric. solve! maximizes the minimum over all registered metrics.

The expression is usually the quantity whose worst-case value is sought, such as f(x_n) - f_\star, \|x_n - x_\star\|^2, or a residual norm. Multiple metrics model the pointwise minimum of several quantities.

add_constraint!(target, constraint)

Add a scalar Constraint to a PEP, function class, operator class, or block partition, depending on target.

For a PEP, the constraint is treated as a global initial/general condition. For a function-like object, it is treated as an additional class-specific constraint and is included with that object's interpolation constraints.

add_psd_matrix!(target, matrix_of_expressions)

Add a positive-semidefinite matrix constraint to a PEP or function-like object. Entries may be Expression objects or real constants.

Global PSD constraints are attached to the problem. Function-local PSD constraints are attached to the internal PEPFunction and compiled with that class's interpolation constraints.

oracle!(func, point)

Evaluate the symbolic oracle of func at point, returning a pair (gradient, value) and registering the evaluation for interpolation constraints.

If func.reuse_gradient is true and the point has already been evaluated, the previously registered pair is returned. Otherwise, a new symbolic subgradient is created while reusing the previous function value when available.

For affine combinations of leaf functions, the oracle either aggregates known leaf oracle values or creates the missing symbolic objects needed to make the aggregate gradient and value consistent.

Returns

(g, f), where g is a Point representing a gradient/subgradient and f is an Expression representing the function value.

gradient!(func, point)

Return the symbolic gradient or subgradient of func at point, creating an oracle evaluation if needed.

For differentiable classes the returned point is interpreted as the gradient. For nonsmooth classes it is an arbitrary selected subgradient. The reuse_gradient flag controls whether repeated calls at the same point must return the same symbolic subgradient.

value!(func, point)

Return the symbolic function value of func at point, creating an oracle evaluation if one has not already been registered.

This is the Julia analogue of evaluating a PEPit function symbolically. It does not compute a numerical value before the PEP is solved; it creates or retrieves the scalar variable that will later be constrained by the class interpolation conditions.

stationary_point!(func; return_gradient_and_function_value=false)

Create a symbolic stationary point of func. When return_gradient_and_function_value=true, also return the zero gradient and associated function value.

The registered oracle triple is (xs, 0, fs), so class interpolation constraints can use xs as an optimizer or zero point when the class supports such an interpretation.

fixed_point!(func)

Create a symbolic fixed point for an operator-like object and return the point, its image, and the associated scalar value.

The registered triple is (x, x, f), which encodes an operator evaluation whose output equals its input. This is used by fixed-point and monotone-operator examples where the oracle value is an operator image rather than a gradient of a scalar objective.

solve!(pep; solver=Clarabel.Optimizer, verbose=true, tracetrick=false,
       logdetiters=0, eig_regularization=1e-3,
       tol_dimension_reduction=1e-5, return_full_model=false)

Build and solve the primal SDP associated with pep. Return the worst-case value unless return_full_model=true, in which case solver variables, constraints, and residual data are returned as a named tuple.

The constructed SDP uses a Gram matrix for all leaf Point objects and one scalar variable for each leaf Expression. Initial conditions, performance metrics, interpolation constraints, and PSD blocks are translated into JuMP constraints before the model is optimized.

Arguments

• pep::PEP: symbolic problem to solve.
• solver: JuMP optimizer constructor, for example Clarabel.Optimizer.
• verbose: print model-building and solver progress when true.
• tracetrick: run a trace-minimization heuristic after the first solve.
• logdetiters: number of log-det heuristic iterations for dimension reduction.
• eig_regularization: regularization used in the log-det heuristic.
• tol_dimension_reduction: allowed objective degradation during dimension reduction.
• return_full_model: return JuMP model data instead of only the worst-case value.

Returns

The worst-case value as a Float64, or a named tuple with model internals when return_full_model=true.

See also solve_dual!, evaluate, and eval_dual.

solve_dual!(pep; solver=Clarabel.Optimizer, verbose=true)

Build the primal SDP for pep, dualize it with Dualization.jl, solve the explicit dual model, and return a DualPEPCertificate.

This routine is useful when the dual multipliers themselves are part of the output, for example when reconstructing a proof certificate for a worst-case bound. It also writes scalar and PSD dual values back to the symbolic constraints so that eval_dual can be used afterwards.

Arguments

• pep::PEP: symbolic performance estimation problem.
• solver: JuMP optimizer constructor used for the dual model.
• verbose: print model-building and solver progress when true.

evaluate(obj)

Return the numerical value assigned to a symbolic object after the PEP has been solved. For a Point, the value is recovered from a Gram matrix factorization.

For a non-leaf point, the value is reconstructed from its leaf decomposition. Calling this before solve! or solve_dual! has populated the numerical realization raises an error.

evaluate(c::Constraint)

Return the numerical residual of c.expression after the PEP has been solved.

For inequalities, feasibility corresponds to a nonpositive residual because the canonical form is expression <= 0. For equalities, feasibility corresponds to a residual close to zero.

evaluate(psd::PSDMatrix)

Return the numerical matrix value of a PSD constraint after the PEP has been solved.

Each symbolic entry is evaluated independently. Calling this before the PEP has been solved raises an error.

eval_dual(obj)

Return the dual multiplier associated with a scalar or PSD constraint after solve! or solve_dual! has populated dual values.

For a scalar Constraint, the return value is a number. For a PSDMatrix, the return value is the corresponding symmetric dual matrix.