Contributing
PEPit is designed for allowing users to easily contribute to add new features to the package. Classes of functions (or operators) as well as black-box oracles can be implemented by following the canvas from respectively PEPit/functions/ (or PEPit/operators/ and PEPit/primitive_steps/).
We encourage authors of research papers presenting novel optimization methods and/or a novel convergence results to submit the corresponding PEPit files in the directory PEPit/examples/.
General guidelines
We kindly ask you follow common guidelines, namely that the provided code:
sticks as much as possible to the PEP8 convention.
is commented with Google style docstring.
is well covered by tests.
is aligned with the documentation.
is also mentioned in the
whatsnew
section of the documentation.
Adding a new function or operator class
To add a new function / operator class, please follow the format used for the other function / operator classes.
In particular:
your class must inherit from the class
Function
and overwrite itsadd_class_constraints
method.the docstring must be complete. In particular, it must contains the list of attributes and arguments as well as an example of usage via the
declare_function
method of the classPEP
. It must also contain a clickable reference to the paper introducing it.
Adding a step / an oracle
To add a new oracle / step,
please add a new file containing the oracle function in PEPit/primitive_steps
.
Remark that transforming the mathematical formulation of an oracle into its PEP equivalent may require additional tricks, see e.g. PEPit/primitive_steps/proximal_step.py, or PEPit/primitive_steps/linear_optimization_step.py.
Please make sure that your docstring contains the mathematical derivation of the latest from the previous.
Adding a new method as an example
We don’t require a specific code format for a new example. However, we ask the associated docstring to be precisely organized as follow:
Define Problem solved (introducing function notations and assumptions).
Name method in boldface formatting.
Introduce performance metric, initial condition and parameters (
performance_metric < tau(parameters) initialization
).Describe method main step and cite reference with specified algorithm.
Provide theoretical result (
Upper/Lower/Tight
in boldface formatting +performance_metric < theoretical_bound initialization
).Reference block containing relevant clickable references (preferably to arxiv with specified version of the paper) in the format: (
First name initial letter
,last name
(YEAR
).Title
.Journal or conference
(Acronym of journal or conference
).Args block containing parameters with their type and short description.
Returns block containing
pepit_tau
andtheoretical_tau
.Example block containing a minimal work example of the coded function.
We provide, in PEPit/examples/example_template.py
, a template that can be filled very quickly
to help the contributor to share their method easily.
New example template
- PEPit.examples.example_template.wc_example_template(arg1, arg2, arg3, verbose=1)[source]
Consider the
CHARACTERISTIC (eg., convex)
minimization problem\[f_\star \triangleq \min_x f(x),\]where \(f\) is
CLASS (eg., smooth convex)
.This code computes a worst-case guarantee for the **
NAME OF THE METHOD
**. That is, it computes the smallest possible \(\tau(arg_1, arg_2, arg_3)\) such that the guarantee\[\text{PERFORMANCE METRIC} \leqslant \tau(arg_1, arg_2, arg_3) \text{ INITIALIZATION}\]is valid, where
NOTATION OF THE OUTPUT
is the output of the **NAME OF THE METHOD
**, and where \(x_\star\) is the minimizer of \(f\). In short, for given values ofARGUMENTS
, \(\tau(arg_1, arg_2, arg_3)\) is computed as the worst-case value of \(\text{PERFORMANCE METRIC}\) when \(\text{INITIALIZATION} \leqslant 1\).Algorithm: The
NAME OF THE METHOD
of this example is provided inREFERENCE WITH SPECIFIED ALGORITHM
by\begin{eqnarray} \text{MAIN STEP} \end{eqnarray}Theoretical guarantee: A
TIGHT, UPPER OR LOWER
guarantee can be found inREFERENCE WITH SPECIFIED THEOREM
:\[\text{PERFORMANCE METRIC} \leqslant \text{THEORETICAL BOUND} \text{ INITIALIZATION}\]References:
- Parameters
arg1 (type1) – description of arg1.
arg2 (type2) – description of arg2.
arg3 (type3) – description of arg3.
verbose (int) –
Level of information details to print.
-1: No verbose at all.
0: This example’s output.
1: This example’s output + PEPit information.
2: This example’s output + PEPit information + CVXPY details.
- Returns
pepit_tau (float) – worst-case value
theoretical_tau (float) – theoretical value
Example
>>> pepit_tau, theoretical_tau = wc_example_template(arg1=value1, arg2=value2, arg3=value3, verbose=1) ``OUTPUT MESSAGE``
New example test template
def test_[NAME_METHOD](self):
PARAMS = PARAMS
wc, theory = wc_[NAME_METHOD](PARAMS=PARAMS, verbose=self.verbose)
# If theoretical upper bound is tight
self.assertAlmostEqual(theory, wc, delta=self.relative_precision * theory)
# If theoretical upper bound is not tight
self.assertLessEqual(wc, theory * (1 + self.relative_precision))
# If theoretical lower bound is not tight
self.assertLessEqual(theory, wc * (1 + self.relative_precision))