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.
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=True)[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 (bool) – if True, print conclusion
- 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=True) ``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))