tfmri.convex.admm_minimize

admm_minimize(function_f, function_g, operator_a=None, operator_b=None, constant_c=None, penalty=1.0, absolute_tolerance=1e-05, relative_tolerance=1e-05, max_iterations=50, linearized=False, f_prox_kwargs=None, g_prox_kwargs=None, name=None)[source]

Applies the ADMM algorithm to minimize a separable convex function.

Minimizes \(f(x) + g(z)\), subject to \(Ax + Bz = c\).

If \(A\), \(B\) and \(c\) are not provided, the constraint defaults to \(x - z = 0\), in which case the problem is equivalent to minimizing \(f(x) + g(x)\).

Parameters

  • function_f – A tfmri.convex.ConvexFunction of shape [..., n] and real or complex dtype.

  • function_g –

    A tfmri.convex.ConvexFunction of shape [..., m] and real or complex dtype.

  • operator_a – A tf.linalg.LinearOperator of shape [..., p, n] and real or complex dtype. Defaults to the identity operator.

  • operator_b – A tf.linalg.LinearOperator of shape [..., p, m] and real or complex dtype. Defaults to the negated identity operator.

  • constant_c – A tf.Tensor of shape [..., p]. Defaults to 0.0.

  • penalty –

    A scalar tf.Tensor. The penalty parameter of the augmented Lagrangian. Also corresponds to the step size of the dual variable update in the scaled form of ADMM.

  • absolute_tolerance –

    A scalar tf.Tensor of real dtype. The absolute tolerance. Defaults to 1e-5.

  • relative_tolerance –

    A scalar tf.Tensor of real dtype. The relative tolerance. Defaults to 1e-5.

  • max_iterations –

    A scalar tf.Tensor of integer dtype. The maximum number of iterations of the ADMM update.

  • linearized – A boolean. If True, use linearized variant of the ADMM algorithm. Linearized ADMM solves problems of the form \(f(x) + g(Ax)\) and only requires evaluation of the proximal operator of g(x). This is useful when the proximal operator of g(Ax) cannot be easily evaluated, but the proximal operator of g(x) can. Defaults to False.

  • f_prox_kwargs – A dict. Keyword arguments to pass to the proximal operator of function_f during the x-minimization step.

  • g_prox_kwargs –

    A dict. Keyword arguments to pass to the proximal operator of function_g during the z-minimization step.

  • name – A str. The name of this operation. Defaults to 'admm_minimize'.

Returns

A namedtuple containing the following fields

  • converged: A boolean tf.Tensor of shape [...] indicating whether the minimum was found within tolerance for each batch member.

  • dual_residual: A real tf.Tensor of shape [...] containing the last tolerance used to evaluate the primal feasibility condition.

  • dual_tolerance: The dual tolerance.

  • f_primal_variable: A real or complex tf.Tensor of shape [..., n] containing the last argument value of f found during the search for each batch member. If the search converged, then this value is the argmin of the objective function, subject to the specified constraint.

  • g_primal_variable: A real or complex tf.Tensor of shape [..., m] containing the last argument value of g found during the search for each batch member. If the search converged, then this value is the argmin of the objective function, subject to the specified constraint.

  • num_iterations: A scalar integer tf.Tensor containing the number of iterations of the ADMM update.

  • primal_residual: A real or complex tf.Tensor of shape [..., p] containing the last primal residual for each batch member.

  • primal_tolerance: A real tf.Tensor of shape [...] containing the last tolerance used to evaluate the primal feasibility condition.

  • scaled_dual_variable: A tf.Tensor of shape [..., p] and real or complex dtype containing the last value of the scaled dual variable found during the search.

References

1

Boyd, S., Parikh, N., & Chu, E. (2011). Distributed optimization and statistical learning via the alternating direction method of multipliers. Now Publishers Inc.

Raises

  • TypeError – If inputs have incompatible types.

  • ValueError – If inputs are incompatible.