API Reference

paramita.modelling module

Expression module-attribute

Expression = Union[Bool, UnaryOperation, BinaryOperation, PseudoBooleanOperation]

Bool

Boolean expression node.

Represents a named boolean variable in the expression system.

name property

name

The name of the boolean variable.

__init__

__init__(name)

Create a boolean variable.

Parameters:

Name	Type	Description	Default
name	str	Name of the variable.	required

Returns:

Type	Description
None	A boolean variable expression.

UnaryOperation

Unary boolean operation node.

Represents an operation with a single operand (e.g. NOT).

operand property

operand

The operand of the unary operation.

operator property

operator

The unary operator represented by this expression.

Type

Bases: Enum

Type of unary boolean operation.

BinaryOperation

Binary boolean operation node.

Represents an operation with two operands (e.g. AND, OR, XOR).

lhs property

lhs

The left-hand operand of the binary operation.

operator property

operator

The binary operator represented by this expression.

rhs property

rhs

The right-hand operand of the binary operation.

Type

Bases: Enum

Type of binary boolean operation.

UnaryIntegerOperation

Unary integer operation node.

Represents a unary arithmetic operation on integer expressions (e.g. negation).

operand property

operand

The operand of the unary integer operation.

operator property

operator

The unary integer operator represented by this expression.

Type

Bases: Enum

Type of unary integer operation.

BinaryIntegerOperation

Binary integer operation node.

Represents a binary arithmetic operation on integer expressions (e.g. +, -, *).

lhs property

lhs

The left-hand operand of the binary integer operation.

operator property

operator

The binary integer operator represented by this expression.

rhs property

rhs

The right-hand operand of the binary integer operation.

Type

Bases: Enum

Type of binary integer operation.

PseudoBooleanOperation

Pseudo-boolean constraint node.

Represents a comparison between integer expressions (e.g. <=, >=, ==).

lhs property

lhs

The left-hand operand of the pseudo-boolean operation.

operator property

operator

The pseudo-boolean operator represented by this expression.

rhs property

rhs

The right-hand operand of the pseudo-boolean operation.

Type

Bases: Enum

Type of pseudo-boolean comparison operation.

And

And(lhs, rhs)

Logical AND of two expressions.

Parameters:

Name	Type	Description	Default
lhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Left-hand expression.	required
rhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Right-hand expression.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	An expression representing lhs AND rhs.

Or

Or(lhs, rhs)

Logical OR of two expressions.

Parameters:

Name	Type	Description	Default
lhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Left-hand expression.	required
rhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Right-hand expression.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	An expression representing lhs OR rhs.

Not

Not(operand)

Logical negation of an expression.

Parameters:

Name	Type	Description	Default
operand	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Expression to negate.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	The negated expression.

If

If(lhs, rhs)

Logical implication.

Parameters:

Name	Type	Description	Default
lhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Antecedent.	required
rhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Consequent.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	An expression representing lhs -> rhs.

Iff

Iff(lhs, rhs)

Logical equivalence.

Parameters:

Name	Type	Description	Default
lhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Left-hand expression.	required
rhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Right-hand expression.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	An expression representing lhs <-> rhs.

Xor

Xor(lhs, rhs)

Exclusive OR of two expressions.

Parameters:

Name	Type	Description	Default
lhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Left-hand expression.	required
rhs	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Right-hand expression.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	An expression representing lhs XOR rhs.

Minus

Minus(operand)

Unary minus for integer expressions.

Parameters:

Name	Type	Description	Default
operand	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Expression to negate.	required

Returns:

Type	Description
int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	The negated expression.

Add

Add(lhs, rhs)

Addition of two integer expressions.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Sum of lhs and rhs.

Subtract

Subtract(lhs, rhs)

Subtraction of two integer expressions.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Difference lhs - rhs.

Multiply

Multiply(lhs, rhs)

Multiplication of two integer expressions.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Product of lhs and rhs.

LessThan

LessThan(lhs, rhs)

Less-than comparison.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Boolean expression for lhs < rhs.

LessOrEqual

LessOrEqual(lhs, rhs)

Less-than-or-equal comparison.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Boolean expression for lhs <= rhs.

Equal

Equal(lhs, rhs)

Equality comparison.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Boolean expression for lhs == rhs.

GreaterOrEqual

GreaterOrEqual(lhs, rhs)

Greater-than-or-equal comparison.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Boolean expression for lhs >= rhs.

GreaterThan

GreaterThan(lhs, rhs)

Greater-than comparison.

Parameters:

Name	Type	Description	Default
lhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Left-hand operand.	required
rhs	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Right-hand operand.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Boolean expression for lhs > rhs.

parse

parse(expr_str)

Parse an expression from a string.

DimacsVariablePool

Pool of DIMACS variables.

Maintains a mapping between named variables and DIMACS integer literals.

decode_literal

decode_literal(literal)

Decode a DIMACS literal into its variable name (if known).

Parameters:

Name	Type	Description	Default
literal	int	DIMACS literal.	required

Returns:

Type	Description
Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | None	Variable name corresponding to the literal.

get_variable

get_variable(name)

Get or create a DIMACS variable for a given name.

If the name has not been seen previously by the pool, a new DIMACS variable is introduced.

Parameters:

Name	Type	Description	Default
name	str	Variable name.	required

Returns:

Type	Description
int	The DIMACS variable associated to this name in this pool.

new_aux

new_aux()

Create a new auxiliary DIMACS variable.

Returns:

Type	Description
Bool	A fresh DIMACS variable not previously used.

add_to_container

add_to_container(expression, cnf_transformer, container, var_pool)

Transforms a boolean expression into CNF and appends the resulting clauses to the given clause container.

Parameters:

Name	Type	Description	Default
expression	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Boolean expression to add to the container.	required
cnf_transformer	Callable[[Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool], Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool]	Transformation applied to the expression.	required
container	ClauseContainer	Clause container where the clauses are added.	required
var_pool	DimacsVariablePool	Variable pool used to allocate and resolve DIMACS variables.	required

add_to_weighted_container

add_to_weighted_container(obj, subject_to, cnf_transformer, container, var_pool)

Encodes an optimization objective and hard constraints into a weighted clause container.

The objective expression must be linear. The hard constraints are first transformed using the provided CNF transformation function before being encoded and added as hard clauses. Terms in the objective that are not clauses are reified.

The returned value corresponds to the constant component of the objective expression.

Parameters:

Name	Type	Description	Default
obj	int | Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool | UnaryIntegerOperation | BinaryIntegerOperation	Linear integer objective expression to encode.	required
subject_to	Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool	Boolean constraints that must hold.	required
cnf_transformer	Callable[[Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool], Bool | UnaryOperation | BinaryOperation | PseudoBooleanOperation | bool]	Transformation applied to constraint expressions prior to CNF conversion.	required
container	WClauseContainer	Weighted clause container where the clauses are added.	required
var_pool	DimacsVariablePool	Variable pool used to allocate and resolve DIMACS variables.	required

Returns:

Type	Description
int	The constant component of the objective expression.