Paganini’s API

Module contents

Paganini

Paganini is a lightweight python library for tuning of multiparametric combinatorial systems.

All the necessary documentation can be found on-line on https://paganini.readthedocs.io/

Use

>>> help(paganini.tutorial)

to see some examples of code usage.

class paganini.expressions.Expr(coeff=1, variables={})

Bases: object

Algebraic expressions (multivariate monomials) in form of \(c x_1^{k_1} x_2^{k_2} \cdots x_m^{k_m}.\)

static cast(other)

Casts its input to an expression.

is_constant

True iff the expression represents a constant.

related(other)

Checks if the two expressions are related, i.e. have the same exponents and perpahs a different coefficient.

class paganini.expressions.VariableType

Bases: enum.Enum

An enumeration.

PLAIN = 1

TYPE = 2

class paganini.expressions.Variable(tuning_param=None)

Bases: paganini.expressions.Expr

Symbolic variables.

is_type_variable

True iff the variable represents a type variable. In other words, if it admits a defining equation.

set_expectation(tuning_param)

class paganini.expressions.Polynomial(expressions)

Bases: object

Polynomials of multivariate algebraic expressions.

static cast(other)

Casts its input to a polynomial.

is_one()

Checks if the polynomial represents a constant one.

static simplify(polynomial)

Simplifies the given polynomial.

specification(no_variables)

Composes a sparse matrix specification of the polynomial. Requires as input a number dictating the number of columns of the constructed matrix (usually the number of variables in the corresponding optimisation problem).

Its output is a tuple consisting of:

1. a sparse matrix representing the polynomial,
2. a vector of logarithms of monomial coefficients,
3. a (collective) constant term representing constant monomials.

The matrix represents expoenents of respective variables.

static sum(series)

Evaluates the sum of the given series.

class paganini.specification.Seq(expression, constraint=None)

Bases: paganini.expressions.Variable

Sequence variables.

register(spec)

Unfolds the Seq definition and registers it in the given system.

class paganini.specification.UCyc(expression, constraint=None)

Bases: paganini.expressions.Variable

Unlabelled Cyc variables.

register(spec)

Unfolds the UCyc definition and registers it in the given system.

class paganini.specification.MSet(expression, constraint=None)

Bases: paganini.expressions.Variable

MSet variables.

register(spec)

Unfolds the MSet definition and registers it in the given system.

class paganini.specification.Set(expression, constraint=None)

Bases: paganini.expressions.Variable

Labelled Set variables.

register(spec)

Unfolds the Set definition and registers it in the given system.

class paganini.specification.Cyc(expression, constraint=None)

Bases: paganini.expressions.Variable

Labelled Cyc variables.

register(spec)

Unfolds the Cyc definition and registers it in the given system.

class paganini.specification.Operator

Bases: enum.Enum

Enumeration of supported constraint signs.

EQ = 2

GEQ = 3

LEQ = 1

UNBOUNDED = 4

class paganini.specification.Constraint(operator, value)

Bases: object

Supported constraints for classes such as SEQ.

static normalise(constraint=None)

class paganini.specification.Type

Bases: enum.Enum

Enumeration of supported system types.

ALGEBRAIC = 1

RATIONAL = 2

class paganini.specification.Params(sys_type)

Bases: object

CVXPY solver parameters initalised with some defaults.

class paganini.specification.Specification(series_truncate=20)

Bases: object

Symbolic system specifications.

add(var, expression)

Includes the given definition in the specification.

check_type()

Checks if the system is algebraic or rational. Note: the current method is heuristic.

discharged_variables

Number of variables discharged in the system.

run_singular_tuner(z, params=None)

Given a (size) variable and a set of tuning parameters, composes an optimisation problem corresponding to an approximate sampler meant for structures of the given type. Variables are tuned so to achieve (in expectation) the marked variable frequencies.

Consider the following example:

>>> sp = Specification()
>>> z, u, M = Variable(), Variable(0.4), Variable()
>>> sp.add(M, z + u * z * M + z * M **2)
>>>
>>> params = Params(Type.ALGEBRAIC)
>>> sp.run_singular_tuner(z, params)

Here, the variable u is marked with a frequency 0.4. The type M represents the type of Motzkin trees, i.e. unary-binary plane trees. Variable z marks their size, whereas u marks the occurrences of unary nodes. The tuning goal is to obtain specific values of z, u, and M, such that the induced branching probabilities lead to a sampler which generates, in expectation, Motzkin trees of infinite (i.e. unbounded) size and around 40% of unary nodes.

Respective variables (including type variables) are decorated with a proper ‘value’. The method returns the CVXPY solution (i.e. the optimal value for the problem, or a string indicating why the problem could not be solved).

run_tuner(t, params=None)

Given the type variable and a set of tuning parameters, composes a (tuning) optimisation problem corresponding to an approximate sampler meant for structures of the given type. Variables are tuned so to achieve (in expectation) the marked variable values.

Consider the following example:

>>> sp = Specification()
>>> z, u, M = Variable(1000), Variable(200), Variable()
>>> sp.add(M, z + u * z * M + z * M **2)
>>> params = Params(Type.ALGEBRAIC)
>>> sp.run_tuner(M, params)

Here, the variables z and u are marked with absolute values 1000 and 200, respectively. The input type represents the type of Motzkin trees, i.e. plane unary-binary trees. Variable z marks their size, whereas u marks the occurrences of unary nodes. The tuning goal is to obtain specific values of z, u, and M, such that the induced branching probabilities lead to a sampler which generates Motzkin trees of size 1000 with around 200 unary nodes (both in expectation).

Respective variables (including type variables) are decorated with a proper ‘value’. The method returns the CVXPY solution (i.e. the optimal value for the problem, or a string indicating why the problem could not be solved).

paganini.specification.leq(n)

Creates a less or equal constraint for the given input.

paganini.specification.geq(n)

Creates a greater or equal constraint for the given input.

paganini.specification.eq(n)

Creates an equal constraint for the given input.