basic_manifold_torch#

CLASS basic_manifold_torch(name,variable_shape, constraint_shape, device = torch.device('cpu'), dtype = torch.float64,  regularize_value = 0.01, safegurad_value = 0)

The class that provides essential materials to transform a manifold optimization problem to its corresponding constraint dissolving function, based on PyTorch.

Parameters:#

  • name (str) – Name of the manifold.

  • variable_shape (tuple of ints) – The shape of the variables of the manifold.

  • constraint shape (tuple of ints) – The shape of the constraints.

  • device (PyTorch device) – The object representing the device on which a torch.Tensor is or will be allocated.

  • dtype (PyTorch dtype) – The object that represents the data type of a torch.Tensor.

  • regularize_value = 0.01 (float, optional) – The value of \(\alpha\).

  • safeguard_value = 0 (float, optional) – The value of \(\gamma\).

Attributes:#

The attributes in the following must be defined in creating a specific manifold class.

Attributes that must be specified#

C(x) (callable)

The constraints \(c(x)\). The shape of C(x) should be the same as variable_shape.

Optional Attributes#

The attributes in the following are optional in creating a specific manifold class. If not provided, the code will automatically interfere these components.

_parameter() (OrdDict)

The ordered dictionary that contains all the variables that changes when device and dtype changes.

m2c(x) (callable)

Flatten the variable of the manifold.

v2m(x) (callable)

Recover flattened variables to its original shape as variable_shape.

Init_point(Xinit = None) (callable)

Generate the initial point.

tensor2array(x) (callable)

Transfer the variable of the manifold to the numpy Nd-array while keep its shape. Default settings are provided in the core.backbone class.

array2tensor(x) (callable)

Transfer the numpy Nd-array to the variable of the manifold while keep its shape. Default settings are provided in the core.backbone class.

JC(x, lambda) (callable)

The Jacobian of C(x). If it is not provided, it will be automatically generated by self.vjp(self.C, X, Lambda).

JC_transpose(x, lambda) (callable)

The transpose of \(J_c(x)\), expressed by matrix-vector production. If it is not provided, it will be automatically generated by self.jvp(self.C, X, Lambda).

A(x) (callable)

The constraint dissolving mapping \(\mathcal{A}(x)\). If it is not provided, the code will be automatically generated. Mathematically, it is generated by

\[ \mathcal{A}(x) = J_c(x) (J_c(x)^\top Jc(x) + (\alpha ||c(x)||^2 + \gamma)I_n )^{-1} c(x). \]

JA(x, d) (callable)

The transposed Jacobian of \(\mathcal{A}(x)\). If it is not provided, the code will be automatically generated by self.vjp(self.A, X, D).

JA_transpose(x, d) (callable)

The transpose (or adjoint) of JA(x), i.e. \(\lim_{t \to 0} \frac{1}{t}(J_A(x+td) -J_A(x)) \). If it is not provided, the code will be automatically generated by self.jvp(self.A, X, D).

C_quad_penalty(x) (callable)

Returns the quadratical penalty term \(||c(x)||^2\).

hessA(X, U, D) (callable)

Returns the Hessian of \(\mathcal{A}(x)\) in a tensor-vector product form. If not provided, it is automatically generated by self.vjp(lambda X: self.JA(X, U), X, D).

hess_feas(X, D) (callable)

Returns the hessian-vector product of \(\frac{1}{2} ||c(x)||^2\).

Feas_eval(X) (callable)

Returns the feasibility of \(x\), measured by value of \(||c(x)||\).

Post_process(X) (callable)

Return the post-processing for X to achieve a point with better feasibility. Default return X.

generate_cdf_fun(obj_fun, beta) (callable)

Return the function value of the constraint dissolving function. obj_fun is a callable function that returns the value of \(f\) at \(x\). beta is a float object that refers to the penalty parameter in the constraint dissolving function.

generate_cdf_grad(obj_grad, beta) (callable)

Return the gradient of the constraint dissolving function. obj_grad is a callable function that returns the gradient of \(f\) at \(x\). beta is a float object that refers to the penalty parameter in the constraint dissolving function.

generate_cdf_hess(obj_grad, obj_hvp, beta) (callable)

Return the hessian of the constraint dissolving function. obj_grad is a callable function that returns the gradient of \(f\) at \(x\). obj_hvp is the hessian-vector product of \(f\) at \(x\), i.e., \(\nabla^2 h(x)[d]\). beta is a float object that refers to the penalty parameter in the constraint dissolving function.