diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..b7d677d --- /dev/null +++ b/404.html @@ -0,0 +1,518 @@ + + + +
+ + + + + + + + + + + + + + +Warning
+In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+If you want to extend the oraqle compiler, or implement your own high-level nodes, it is easiest to extend one of the existing abstract node classes.
+ + + + + + + + + + + + + +Warning
+In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+The add_chains
module contains tools for generating addition chains.
add_chains
+
+
+¶Tools for generating addition chains using different constraints and objectives.
+ + + + + + + + +
addition_chains
+
+
+¶Tools for generating short addition chains using a MaxSAT formulation.
+ + + + + + + + +
thurber_bounds(target, max_size)
+
+¶Returns the Thurber bounds for a given target and a maximum size of the addition chain.
+ +
add_chain(target, max_depth, strict_cost_max, squaring_cost, solver, encoding, thurber, min_size, precomputed_values)
+
+¶Generates a minimum-cost addition chain for a given target, abiding to the constraints.
+ + +Parameters:
+target
+ (int
)
+ –
+ The target integer.
+max_depth
+ (Optional[int]
)
+ –
+ The maximum depth of the addition chain
+strict_cost_max
+ (float
)
+ –
+ A strict upper bound on the cost of the addition chain. I.e., cost(chain) < strict_cost_max.
+squaring_cost
+ (float
)
+ –
+ The cost of doubling (squaring), compared to other additions (multiplications), which cost 1.0.
+solver
+ (str
)
+ –
+ Name of the SAT solver, e.g. "glucose421" for glucose 4.2.1. See: https://pysathq.github.io/docs/html/api/solvers.html.
+encoding
+ (int
)
+ –
+ The encoding to use for cardinality constraints. See: https://pysathq.github.io/docs/html/api/card.html#pysat.card.EncType.
+thurber
+ (bool
)
+ –
+ Whether to use the Thurber bounds, which provide lower bounds for the elements in the chain. The bounds are ignored when precomputed_values = True
.
min_size
+ (int
)
+ –
+ The minimum size of the chain. It is always possible to use math.ceil(math.log2(target))
.
precomputed_values
+ (Optional[Tuple[Tuple[int, int], ...]]
)
+ –
+ If there are any precomputed values that can be used for free, they can be specified as a tuple of pairs (value, chain_depth).
+Raises:
+TimeoutError
+ –
+ If the global MAXSAT_TIMEOUT is not None, and it is reached before a maxsat instance could be solved.
+Returns:
+Optional[List[Tuple[int, int]]]
+ –
+ A minimum-cost addition chain, if it exists.
+
addition_chains_front
+
+
+¶Tools for generating addition chains that trade off depth and cost.
+ + + + + + + + +
chain_depth(chain, precomputed_values=None, modulus=None)
+
+¶Return the depth of the addition chain.
+ +
gen_pareto_front(target, modulus, squaring_cost, solver='glucose42', encoding=1, thurber=True, precomputed_values=None)
+
+¶Returns a Pareto front of addition chains, trading of cost and depth.
+ +
addition_chains_heuristic
+
+
+¶This module contains functions for finding addition chains, while sometimes resorting to heuristics to prevent long computations.
+ + + + + + + + +
add_chain_guaranteed(target, modulus, squaring_cost, solver='glucose421', encoding=1, thurber=True, precomputed_values=None)
+
+
+ cached
+
+
+¶Always generates an addition chain for a given target, which is suboptimal if the inputs are too large.
+In some cases, the result is not necessarily optimal. These are the cases where we resort to a heuristic. +This currently happens if: +- The target exceeds 1000. +- The modulus (if provided) exceeds 200. +- MAXSAT_TIMEOUT is not None and a MaxSAT instance timed out
+Note
+This function is useful for preventing long computation, but the result is not guaranteed to be (close to) optimal.
+Unlike add_chain
, this function will always return an addition chain.
Parameters:
+target
+ (int
)
+ –
+ The target integer.
+modulus
+ (Optional[int]
)
+ –
+ Modulus to take into account. In an exponentiation chain, this is the modulus in the exponent, i.e. x^target mod p corresponds to modulus = p - 1
.
squaring_cost
+ (float
)
+ –
+ The cost of doubling (squaring), compared to other additions (multiplications), which cost 1.0.
+solver
+ (str
, default:
+ 'glucose421'
+)
+ –
+ Name of the SAT solver, e.g. "glucose421" for glucose 4.2.1. See: https://pysathq.github.io/docs/html/api/solvers.html.
+encoding
+ (int
, default:
+ 1
+)
+ –
+ The encoding to use for cardinality constraints. See: https://pysathq.github.io/docs/html/api/card.html#pysat.card.EncType.
+thurber
+ (bool
, default:
+ True
+)
+ –
+ Whether to use the Thurber bounds, which provide lower bounds for the elements in the chain. The bounds are ignored when precomputed_values = True
.
precomputed_values
+ (Optional[Tuple[Tuple[int, int], ...]]
, default:
+ None
+)
+ –
+ If there are any precomputed values that can be used for free, they can be specified as a tuple of pairs (value, chain_depth).
+Raises:
+TimeoutError
+ –
+ If the global MAXSAT_TIMEOUT is not None, and it is reached before a maxsat instance could be solved.
+Returns:
+List[Tuple[int, int]]
+ –
+ An addition chain.
+
addition_chains_mod
+
+
+¶Tools for computing addition chains, taking into account the modular nature of the algebra.
+ + + + + + + + +
hw(n)
+
+¶Returns the Hamming weight of n.
+ +
size_lower_bound(target)
+
+¶Returns a lower bound on the size of the addition chain for this target.
+ +
cost_lower_bound_monotonic(target, squaring_cost)
+
+¶Returns a lower bound on the cost of the addition chain for this target. The bound is guaranteed to grow monotonically with the target.
+ +
chain_cost(chain, squaring_cost)
+
+¶Returns the cost of the addition chain, considering doubling (squaring) to be cheaper than other additions (multiplications).
+ +
add_chain_modp(target, modulus, max_depth, strict_cost_max, squaring_cost, solver, encoding, thurber, min_size, precomputed_values=None)
+
+¶Computes an addition chain for target modulo p with the given constraints and optimization parameters.
+The precomputed_powers are an optional set of powers that have previously been computed along with their depth. +This means that those powers can be reused for free.
+ + +Returns:
+Optional[List[Tuple[int, int]]]
+ –
+ If it exists, a minimal addition chain meeting the given constraints and optimization parameters.
+
memoization
+
+
+¶This module contains tools for memoizing addition chains, as these are expensive to compute.
+ + + + + + + + +
cache_to_disk(file_name, ignore_args)
+
+¶This decorator caches the calls to this function in a file on disk, ignoring the arguments listed in ignore_args
.
Returns:
+A cached output
+
solving
+
+
+¶Tools for solving SAT formulations.
+ + + + + + + + +
solve(wcnf, solver, strict_cost_max)
+
+¶This code is adapted from pysat's internal code to stop when we have reached a maximum cost.
+ + +Returns:
+Optional[List[int]]
+ –
+ A list containing the assignment (where 3 indicates that 3=True and -3 indicates that 3=False), or None if the wcnf is unsatisfiable.
+
extract_indices(sequence, precomputed_values=None, modulus=None)
+
+¶Returns the indices for each step of the addition chain.
+If n precomputed values are provided, then these are considered to be the first n indices after x (i.e. x has index 0, followed by 1, ..., n representing the precomputed values).
+ +
solve_with_time_limit(wcnf, solver, strict_cost_max, timeout_secs)
+
+¶This code is adapted from pysat's internal code to stop when we have reached a maximum cost.
+ + +Raises:
+TimeoutError
+ –
+ When a timeout occurs (after timeout_secs
seconds)
Returns:
+Optional[List[int]]
+ –
+ A list containing the assignment (where 3 indicates that 3=True and -3 indicates that 3=False), or None if the wcnf is unsatisfiable.
+Warning
+In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
Circuit
+
+
+¶Represents a circuit over a fixed finite field that can be turned into an arithmetic circuit. Behind the scenes this is a directed acyclic graph (DAG). The circuit only has references to the outputs.
+ + + + + + + + + +
__init__(outputs)
+
+¶Initialize a circuit with the given outputs
.
evaluate(actual_inputs)
+
+¶Evaluates the circuit with the given named inputs.
+This function does not error if it is given more inputs than necessary, but it will error if one is missing.
+ + +Returns:
+List[FieldArray]
+ –
+ Evaluated output in plain text.
+
to_graph(file_name)
+
+¶Saves a DOT file representing the circuit as a graph at the given file_name
.
to_pdf(file_name)
+
+¶Saves a PDF file representing the circuit as a graph at the given file_name
.
to_svg(file_name)
+
+¶Saves an SVG file representing the circuit as a graph at the given file_name
.
display_graph(metadata=None)
+
+¶Displays the circuit in a Python notebook.
+ +
eliminate_subexpressions()
+
+¶Perform semantic common subexpression elimination on all outputs.
+ +
is_equivalent(other)
+
+¶Returns whether the two circuits are semantically equivalent.
+False positives do not occure but false negatives do.
+ +
arithmetize(strategy='best-effort')
+
+¶Arithmetizes this circuit by calling arithmetize on all outputs.
+This replaces all high-level operations with arithmetic operations (constants, additions, and multiplications). +The current implementation only aims at reducing the total number of multiplications.
+ + +Returns:
+ArithmeticCircuit
+ –
+ An equivalent arithmetic circuit with low multiplicative size.
+
arithmetize_depth_aware(cost_of_squaring=1.0)
+
+¶Perform depth-aware arithmetization on this circuit.
+Failure
+The current implementation only supports circuits with a single output.
+This function replaces high-level nodes with arithmetic operations (constants, additions, and multiplications).
+ + +Returns:
+List[Tuple[int, int, ArithmeticCircuit]]
+ –
+ A list with tuples containing the multiplicative depth, the multiplicative cost, and the generated arithmetization from low to high depth.
+
ArithmeticCircuit
+
+
+¶
+ Bases: Circuit
Represents an arithmetic circuit over a fixed finite field, so it only contains arithmetic nodes.
+ + + + + + + + + +
__init__(outputs)
+
+¶Initialize a circuit with the given outputs
.
evaluate(actual_inputs)
+
+¶Evaluates the circuit with the given named inputs.
+This function does not error if it is given more inputs than necessary, but it will error if one is missing.
+ + +Returns:
+List[FieldArray]
+ –
+ Evaluated output in plain text.
+
to_graph(file_name)
+
+¶Saves a DOT file representing the circuit as a graph at the given file_name
.
to_pdf(file_name)
+
+¶Saves a PDF file representing the circuit as a graph at the given file_name
.
to_svg(file_name)
+
+¶Saves an SVG file representing the circuit as a graph at the given file_name
.
display_graph(metadata=None)
+
+¶Displays the circuit in a Python notebook.
+ +
eliminate_subexpressions()
+
+¶Perform semantic common subexpression elimination on all outputs.
+ +
is_equivalent(other)
+
+¶Returns whether the two circuits are semantically equivalent.
+False positives do not occure but false negatives do.
+ +
arithmetize(strategy='best-effort')
+
+¶Arithmetizes this circuit by calling arithmetize on all outputs.
+This replaces all high-level operations with arithmetic operations (constants, additions, and multiplications). +The current implementation only aims at reducing the total number of multiplications.
+ + +Returns:
+ArithmeticCircuit
+ –
+ An equivalent arithmetic circuit with low multiplicative size.
+
arithmetize_depth_aware(cost_of_squaring=1.0)
+
+¶Perform depth-aware arithmetization on this circuit.
+Failure
+The current implementation only supports circuits with a single output.
+This function replaces high-level nodes with arithmetic operations (constants, additions, and multiplications).
+ + +Returns:
+List[Tuple[int, int, ArithmeticCircuit]]
+ –
+ A list with tuples containing the multiplicative depth, the multiplicative cost, and the generated arithmetization from low to high depth.
+
multiplicative_depth()
+
+¶Returns the multiplicative depth of the circuit.
+ +
multiplicative_size()
+
+¶Returns the multiplicative size (number of multiplications) of the circuit.
+ +
multiplicative_cost(cost_of_squaring)
+
+¶Returns the multiplicative cost of the circuit.
+ +
generate_program()
+
+¶Returns an arithmetic program for this arithmetic circuit.
+ +
summands_between_multiplications()
+
+¶Computes the maximum number of summands between two consecutive multiplications in this circuit.
+Failure
+This currently returns the hardcoded value 10
+Returns:
+int
+ –
+ The highest number of summands between two consecutive multiplications
+
generate_code(filename, iterations=1, measure_time=False, decrypt_outputs=False)
+
+¶Generates an HElib implementation of the circuit.
+If decrypt_outputs is True, prints the decrypted output. +Otherwise, it prints whether the ciphertext has noise budget remaining (i.e. it is correct with high probability).
+Note
+Decryption is part of the measured run time.
+Parameters:
+filename
+ (str
)
+ –
+ Test
+iterations
+ (int
, default:
+ 1
+)
+ –
+ Number of times to run the circuit
+measure_time
+ (bool
, default:
+ False
+)
+ –
+ Whether to output a measurement of the total run time
+decrypt_outputs
+ (bool
, default:
+ False
+)
+ –
+ Whether to print the decrypted outputs, or to simply check if there is noise budget remaining
+Returns:
+Tuple[int, int, int, int]
+ –
+ Parameters that were chosen: (ring dimension m, Hensel lifting = 1, bits in the modchain, columns in key switching = 3).
+Warning
+In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+The easiest way is using: +
arithmetic_circuit.generate_code()
+
If you want to extend the oraqle compiler, or implement your own code generation, you can use the following instructions to do so.
+
ArithmeticInstruction
+
+
+¶
+ Bases: ABC
An abstract arithmetic instruction that computes an operation in an arithmetic circuit using a stack.
+ + + + + + + + + +
__init__(stack_index)
+
+¶Initialize an instruction that writes it output to the stack at stack_index
.
evaluate(stack, inputs)
+
+
+ abstractmethod
+
+
+¶Executes the instruction on plaintext inputs without using encryption, keeping track of the plaintext values in the stack.
+ +
generate_code(stack_initialized, decrypt_outputs)
+
+
+ abstractmethod
+
+
+¶Generates code for this instruction, keeping track of which places of the stack are already initialized.
+ +
InputInstruction
+
+
+¶
+ Bases: ArithmeticInstruction
Writes an input to the stack.
+ + + + + + + + + +
__init__(stack_index, name)
+
+¶Initialize an InputInstruction
that places the input with the given name
in the stack at index stack_index
.
evaluate(stack, inputs)
+
+¶
generate_code(stack_initialized, _decrypt_outputs)
+
+¶
AdditionInstruction
+
+
+¶
+ Bases: ArithmeticInstruction
Reads two elements from the stack, adds them, and writes the result to the stack.
+ + + + + + + + + +
__init__(stack_index, left_stack_index, right_stack_index)
+
+¶Initialize an instruction that adds the elements at left_stack_index
and right_stack_index
, placing the result at stack_index
.
evaluate(stack, _inputs)
+
+¶
generate_code(stack_initialized, _decrypt_outputs)
+
+¶
MultiplicationInstruction
+
+
+¶
+ Bases: ArithmeticInstruction
Reads two elements from the stack, multiplies them, and writes the result to the stack.
+ + + + + + + + + +
__init__(stack_index, left_stack_index, right_stack_index)
+
+¶Initialize an instruction that multiplies the elements at left_stack_index
and right_stack_index
, placing the result at stack_index
.
evaluate(stack, _inputs)
+
+¶
generate_code(stack_initialized, _decrypt_outputs)
+
+¶
ConstantAdditionInstruction
+
+
+¶
+ Bases: ArithmeticInstruction
Reads an element from the stack, adds a constant to it it, and writes the result to the stack.
+ + + + + + + + + +
__init__(stack_index, input_stack_index, constant)
+
+¶Initialize an instruction that adds constant
to the element at input_stack_index
, placing the result at stack_index
.
evaluate(stack, _inputs)
+
+¶
generate_code(stack_initialized, _decrypt_outputs)
+
+¶
ConstantMultiplicationInstruction
+
+
+¶
+ Bases: ArithmeticInstruction
Reads an element from the stack, multiplies it with a constant, and writes the result to the stack.
+ + + + + + + + + +
__init__(stack_index, input_stack_index, constant)
+
+¶Initialize an instruction that multiplies the element at input_stack_index
with constant
, placing the result at stack_index
.
evaluate(stack, _inputs)
+
+¶
generate_code(stack_initialized, _decrypt_outputs)
+
+¶
OutputInstruction
+
+
+¶
+ Bases: ArithmeticInstruction
Outputs an element from the stack.
+ + + + + + + + + + + +
ArithmeticProgram
+
+
+¶An ArithmeticProgram represents an ordered set of arithmetic operations that compute an arithmetic circuit.
+The easiest way to obtain an ArithmeticProgram
of an ArithmeticCircuit
is to call ArithmeticCircuit.generate_program()
.
__init__(instructions, stack_size, gf)
+
+¶Initialize an ArithmeticProgram
from a list of instructions
.
The user must specify an upper bound on the stack_size
required.
execute(inputs)
+
+¶Executes the arithmetic program on plaintext inputs without using encryption.
+ + +Raises:
+Exception
+ –
+ If there were no outputs in this program.
+Returns: +The first output in this program.
+ +
generate_code(decrypt_outputs)
+
+¶Generates HElib code for this program.
+If decrypt_outputs
is true, then the generated code will decrypt the outputs at the end of the circuit.
Returns:
+str
+ –
+ The generated code as a string.
+...
+ + + + + + + + + + + + + +Warning
+In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+
And
+
+
+¶
+ Bases: CommutativeUniqueReducibleNode
Performs an AND operation over several operands. The user must ensure that the operands are Booleans.
+ + + + + + + + + +
__init__(operands, gf)
+
+¶Initialize a node with the given set as the operands. None of the operands can be a constant.
+ +
apply_function_to_operands(function)
+
+¶
replace_operands_using_function(function)
+
+¶
evaluate(actual_inputs)
+
+¶
clear_cache(already_cleared)
+
+¶Clears any cached values of the node and any of its operands.
+ +
to_graph(graph_builder)
+
+¶Adds this node to the graph as well as its edges.
+ + +Returns:
+int
+ –
+ The identifier of this Node
in the DotFile
.
__hash__()
+
+¶
is_equivalent(other)
+
+¶
eliminate_common_subexpressions(terms)
+
+¶Eliminates duplicate subexpressions that are equivalent (as defined by a node's __eq__
and __hash__
method).
Returns:
+Node
+ –
+ A Node
that must replace the previous expression.
count_parents()
+
+¶Counts the total number of nodes in this subcircuit.
+ +
reset_parent_count()
+
+¶Resets the cached number of nodes in this subcircuit to 0.
+ +
arithmetize(strategy)
+
+¶
arithmetize_depth_aware(cost_of_squaring)
+
+¶
to_arithmetic()
+
+¶Outputs this node's equivalent ArithmeticNode. Errors if this node does not have a direct arithmetic equivalent.
+ + +Raises:
+Exception
+ –
+ If there is no direct arithmetic equivalent.
+
add(other, flatten=True)
+
+¶Performs a summation between self
and other
, possibly flattening any sums.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Sum
node or a Constant
representing self & other.
__add__(other)
+
+¶
__radd__(other)
+
+¶
mul(other, flatten=True)
+
+¶Performs a multiplication between self
and other
, possibly flattening any products.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Product
node or a Constant
representing self & other.
__mul__(other)
+
+¶
bool_or(other, flatten=True)
+
+¶Performs an OR operation between self
and other
, possibly flattening the result into an OR operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Or
node or a Constant
representing self & other.
__or__(other)
+
+¶
bool_and(other, flatten=True)
+
+¶Performs an AND operation between self
and other
, possibly flattening the result into an AND operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened And
node or a Constant
representing self & other.
__and__(other)
+
+¶
__lt__(other)
+
+¶
__gt__(other)
+
+¶
__le__(other)
+
+¶
__ge__(other)
+
+¶
__neg__()
+
+¶
__invert__()
+
+¶
__pow__(other)
+
+¶
__sub__(other)
+
+¶
__rsub__(other)
+
+¶
__eq__(other)
+
+¶
and_flatten(other)
+
+¶Performs an AND operation with other
, flattening the And
node if either of the two is also an And
and absorbing Constant
s.
Returns:
+Node
+ –
+ An And
node containing the flattened AND operation, or a Constant
node.
Or
+
+
+¶
+ Bases: CommutativeUniqueReducibleNode
Performs an OR operation over several operands. The user must ensure that the operands are Booleans.
+ + + + + + + + + +
__init__(operands, gf)
+
+¶Initialize a node with the given set as the operands. None of the operands can be a constant.
+ +
apply_function_to_operands(function)
+
+¶
replace_operands_using_function(function)
+
+¶
evaluate(actual_inputs)
+
+¶
clear_cache(already_cleared)
+
+¶Clears any cached values of the node and any of its operands.
+ +
to_graph(graph_builder)
+
+¶Adds this node to the graph as well as its edges.
+ + +Returns:
+int
+ –
+ The identifier of this Node
in the DotFile
.
__hash__()
+
+¶
is_equivalent(other)
+
+¶
eliminate_common_subexpressions(terms)
+
+¶Eliminates duplicate subexpressions that are equivalent (as defined by a node's __eq__
and __hash__
method).
Returns:
+Node
+ –
+ A Node
that must replace the previous expression.
count_parents()
+
+¶Counts the total number of nodes in this subcircuit.
+ +
reset_parent_count()
+
+¶Resets the cached number of nodes in this subcircuit to 0.
+ +
arithmetize(strategy)
+
+¶
arithmetize_depth_aware(cost_of_squaring)
+
+¶
to_arithmetic()
+
+¶Outputs this node's equivalent ArithmeticNode. Errors if this node does not have a direct arithmetic equivalent.
+ + +Raises:
+Exception
+ –
+ If there is no direct arithmetic equivalent.
+
add(other, flatten=True)
+
+¶Performs a summation between self
and other
, possibly flattening any sums.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Sum
node or a Constant
representing self & other.
__add__(other)
+
+¶
__radd__(other)
+
+¶
mul(other, flatten=True)
+
+¶Performs a multiplication between self
and other
, possibly flattening any products.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Product
node or a Constant
representing self & other.
__mul__(other)
+
+¶
bool_or(other, flatten=True)
+
+¶Performs an OR operation between self
and other
, possibly flattening the result into an OR operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Or
node or a Constant
representing self & other.
__or__(other)
+
+¶
bool_and(other, flatten=True)
+
+¶Performs an AND operation between self
and other
, possibly flattening the result into an AND operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened And
node or a Constant
representing self & other.
__and__(other)
+
+¶
__lt__(other)
+
+¶
__gt__(other)
+
+¶
__le__(other)
+
+¶
__ge__(other)
+
+¶
__neg__()
+
+¶
__invert__()
+
+¶
__pow__(other)
+
+¶
__sub__(other)
+
+¶
__rsub__(other)
+
+¶
__eq__(other)
+
+¶
or_flatten(other)
+
+¶Performs an OR operation with other
, flattening the Or
node if either of the two is also an Or
and absorbing Constant
s.
Returns:
+Node
+ –
+ An Or
node containing the flattened OR operation, or a Constant
node.
Neg
+
+
+¶
+ Bases: UnivariateNode
A node that negates a Boolean input.
+ + + + + + + + + +
__init__(node, gf)
+
+¶Initialize a univariate node.
+ +
apply_function_to_operands(function)
+
+¶
replace_operands_using_function(function)
+
+¶
evaluate(actual_inputs)
+
+¶
clear_cache(already_cleared)
+
+¶Clears any cached values of the node and any of its operands.
+ +
to_graph(graph_builder)
+
+¶
__hash__()
+
+¶
is_equivalent(other)
+
+¶Check whether self
is semantically equivalent to other
.
This function may have false negatives but it should never return false positives.
+`True` if `self` is semantically equivalent to `other`, `False` if they are not or that they cannot be shown to be equivalent.
+
+
+
eliminate_common_subexpressions(terms)
+
+¶Eliminates duplicate subexpressions that are equivalent (as defined by a node's __eq__
and __hash__
method).
Returns:
+Node
+ –
+ A Node
that must replace the previous expression.
count_parents()
+
+¶Counts the total number of nodes in this subcircuit.
+ +
reset_parent_count()
+
+¶Resets the cached number of nodes in this subcircuit to 0.
+ +
arithmetize(strategy)
+
+¶
arithmetize_depth_aware(cost_of_squaring)
+
+¶
to_arithmetic()
+
+¶Outputs this node's equivalent ArithmeticNode. Errors if this node does not have a direct arithmetic equivalent.
+ + +Raises:
+Exception
+ –
+ If there is no direct arithmetic equivalent.
+
add(other, flatten=True)
+
+¶Performs a summation between self
and other
, possibly flattening any sums.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Sum
node or a Constant
representing self & other.
__add__(other)
+
+¶
__radd__(other)
+
+¶
mul(other, flatten=True)
+
+¶Performs a multiplication between self
and other
, possibly flattening any products.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Product
node or a Constant
representing self & other.
__mul__(other)
+
+¶
bool_or(other, flatten=True)
+
+¶Performs an OR operation between self
and other
, possibly flattening the result into an OR operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Or
node or a Constant
representing self & other.
__or__(other)
+
+¶
bool_and(other, flatten=True)
+
+¶Performs an AND operation between self
and other
, possibly flattening the result into an AND operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened And
node or a Constant
representing self & other.
__and__(other)
+
+¶
__lt__(other)
+
+¶
__gt__(other)
+
+¶
__le__(other)
+
+¶
__ge__(other)
+
+¶
__neg__()
+
+¶
__invert__()
+
+¶
__pow__(other)
+
+¶
__sub__(other)
+
+¶
__rsub__(other)
+
+¶
__eq__(other)
+
+¶
operands()
+
+¶
set_operands(operands)
+
+¶
operation(operands)
+
+¶These operations are fundamental arithmetic operations, so they will stay the same when they are arithmetized.
+
Subtraction
+
+
+¶
+ Bases: NonCommutativeBinaryNode
Represents a subtraction, which can be arithmetized using addition and constant-multiplication.
+ + + + + + + + + +
__init__(left, right, gf)
+
+¶Initialize a Node that performs an operation between two operands that is not commutative.
+ +
apply_function_to_operands(function)
+
+¶
replace_operands_using_function(function)
+
+¶
evaluate(actual_inputs)
+
+¶
clear_cache(already_cleared)
+
+¶Clears any cached values of the node and any of its operands.
+ +
to_graph(graph_builder)
+
+¶
__hash__()
+
+¶
is_equivalent(other)
+
+¶
eliminate_common_subexpressions(terms)
+
+¶Eliminates duplicate subexpressions that are equivalent (as defined by a node's __eq__
and __hash__
method).
Returns:
+Node
+ –
+ A Node
that must replace the previous expression.
count_parents()
+
+¶Counts the total number of nodes in this subcircuit.
+ +
reset_parent_count()
+
+¶Resets the cached number of nodes in this subcircuit to 0.
+ +
arithmetize(strategy)
+
+¶
arithmetize_depth_aware(cost_of_squaring)
+
+¶
to_arithmetic()
+
+¶Outputs this node's equivalent ArithmeticNode. Errors if this node does not have a direct arithmetic equivalent.
+ + +Raises:
+Exception
+ –
+ If there is no direct arithmetic equivalent.
+
add(other, flatten=True)
+
+¶Performs a summation between self
and other
, possibly flattening any sums.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Sum
node or a Constant
representing self & other.
__add__(other)
+
+¶
__radd__(other)
+
+¶
mul(other, flatten=True)
+
+¶Performs a multiplication between self
and other
, possibly flattening any products.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Product
node or a Constant
representing self & other.
__mul__(other)
+
+¶
bool_or(other, flatten=True)
+
+¶Performs an OR operation between self
and other
, possibly flattening the result into an OR operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Or
node or a Constant
representing self & other.
__or__(other)
+
+¶
bool_and(other, flatten=True)
+
+¶Performs an AND operation between self
and other
, possibly flattening the result into an AND operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened And
node or a Constant
representing self & other.
__and__(other)
+
+¶
__lt__(other)
+
+¶
__gt__(other)
+
+¶
__le__(other)
+
+¶
__ge__(other)
+
+¶
__neg__()
+
+¶
__invert__()
+
+¶
__pow__(other)
+
+¶
__sub__(other)
+
+¶
__rsub__(other)
+
+¶
__eq__(other)
+
+¶
operands()
+
+¶
set_operands(operands)
+
+¶
operation(operands)
+
+¶
Power
+
+
+¶
+ Bases: UnivariateNode
Represents an exponentiation: x ** constant.
+ + + + + + + + + +
apply_function_to_operands(function)
+
+¶
replace_operands_using_function(function)
+
+¶
evaluate(actual_inputs)
+
+¶
clear_cache(already_cleared)
+
+¶Clears any cached values of the node and any of its operands.
+ +
to_graph(graph_builder)
+
+¶
__hash__()
+
+¶
is_equivalent(other)
+
+¶Check whether self
is semantically equivalent to other
.
This function may have false negatives but it should never return false positives.
+`True` if `self` is semantically equivalent to `other`, `False` if they are not or that they cannot be shown to be equivalent.
+
+
+
eliminate_common_subexpressions(terms)
+
+¶Eliminates duplicate subexpressions that are equivalent (as defined by a node's __eq__
and __hash__
method).
Returns:
+Node
+ –
+ A Node
that must replace the previous expression.
count_parents()
+
+¶Counts the total number of nodes in this subcircuit.
+ +
reset_parent_count()
+
+¶Resets the cached number of nodes in this subcircuit to 0.
+ +
arithmetize(strategy)
+
+¶
arithmetize_depth_aware(cost_of_squaring)
+
+¶
to_arithmetic()
+
+¶Outputs this node's equivalent ArithmeticNode. Errors if this node does not have a direct arithmetic equivalent.
+ + +Raises:
+Exception
+ –
+ If there is no direct arithmetic equivalent.
+
add(other, flatten=True)
+
+¶Performs a summation between self
and other
, possibly flattening any sums.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Sum
node or a Constant
representing self & other.
__add__(other)
+
+¶
__radd__(other)
+
+¶
mul(other, flatten=True)
+
+¶Performs a multiplication between self
and other
, possibly flattening any products.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Product
node or a Constant
representing self & other.
__mul__(other)
+
+¶
bool_or(other, flatten=True)
+
+¶Performs an OR operation between self
and other
, possibly flattening the result into an OR operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Or
node or a Constant
representing self & other.
__or__(other)
+
+¶
bool_and(other, flatten=True)
+
+¶Performs an AND operation between self
and other
, possibly flattening the result into an AND operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened And
node or a Constant
representing self & other.
__and__(other)
+
+¶
__lt__(other)
+
+¶
__gt__(other)
+
+¶
__le__(other)
+
+¶
__ge__(other)
+
+¶
__neg__()
+
+¶
__invert__()
+
+¶
__pow__(other)
+
+¶
__sub__(other)
+
+¶
__rsub__(other)
+
+¶
__eq__(other)
+
+¶
operands()
+
+¶
set_operands(operands)
+
+¶
operation(operands)
+
+¶
__init__(node, exponent, gf)
+
+¶Initialize a Power
node that exponentiates node
with exponent
.
UnivariatePoly
+
+
+¶
+ Bases: UnivariateNode
Evaluation of a univariate polynomial.
+ + + + + + + + + +
apply_function_to_operands(function)
+
+¶
replace_operands_using_function(function)
+
+¶
evaluate(actual_inputs)
+
+¶
clear_cache(already_cleared)
+
+¶Clears any cached values of the node and any of its operands.
+ +
to_graph(graph_builder)
+
+¶
__hash__()
+
+¶
is_equivalent(other)
+
+¶Check whether self
is semantically equivalent to other
.
This function may have false negatives but it should never return false positives.
+`True` if `self` is semantically equivalent to `other`, `False` if they are not or that they cannot be shown to be equivalent.
+
+
+
eliminate_common_subexpressions(terms)
+
+¶Eliminates duplicate subexpressions that are equivalent (as defined by a node's __eq__
and __hash__
method).
Returns:
+Node
+ –
+ A Node
that must replace the previous expression.
count_parents()
+
+¶Counts the total number of nodes in this subcircuit.
+ +
reset_parent_count()
+
+¶Resets the cached number of nodes in this subcircuit to 0.
+ +
arithmetize(strategy)
+
+¶
arithmetize_depth_aware(cost_of_squaring)
+
+¶
to_arithmetic()
+
+¶Outputs this node's equivalent ArithmeticNode. Errors if this node does not have a direct arithmetic equivalent.
+ + +Raises:
+Exception
+ –
+ If there is no direct arithmetic equivalent.
+
add(other, flatten=True)
+
+¶Performs a summation between self
and other
, possibly flattening any sums.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Sum
node or a Constant
representing self & other.
__add__(other)
+
+¶
__radd__(other)
+
+¶
mul(other, flatten=True)
+
+¶Performs a multiplication between self
and other
, possibly flattening any products.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Product
node or a Constant
representing self & other.
__mul__(other)
+
+¶
bool_or(other, flatten=True)
+
+¶Performs an OR operation between self
and other
, possibly flattening the result into an OR operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Or
node or a Constant
representing self & other.
__or__(other)
+
+¶
bool_and(other, flatten=True)
+
+¶Performs an AND operation between self
and other
, possibly flattening the result into an AND operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened And
node or a Constant
representing self & other.
__and__(other)
+
+¶
__lt__(other)
+
+¶
__gt__(other)
+
+¶
__le__(other)
+
+¶
__ge__(other)
+
+¶
__neg__()
+
+¶
__invert__()
+
+¶
__pow__(other)
+
+¶
__sub__(other)
+
+¶
__rsub__(other)
+
+¶
__eq__(other)
+
+¶
operands()
+
+¶
set_operands(operands)
+
+¶
operation(operands)
+
+¶
__init__(node, coefficients, gf)
+
+¶Initialize a univariate polynomial with the given coefficients from least to highest order.
+ +
from_function(node, gf, function)
+
+
+ classmethod
+
+
+¶Interpolate a univariate polynomial for the given function.
+A UnivariatePoly whose coefficients compute the function
on all inputs.
arithmetize_custom(strategy)
+
+¶Compute an arithmetization along with a dictionary of precomputed powers.
+An arithmetization and a dictionary of previously computed powers.
+ +
arithmetize_depth_aware_custom(cost_of_squaring)
+
+¶Compute a depth-aware arithmetization as well as a dictionary indexed by the depth of the nodes in the front. The dictionary stores precomputed powers.
+A CostParetoFront with the depth-aware arithmetization and a dictionary indexed by the depth of the nodes in the front, returning a dictionary with previously computed powers.
+ +
IfElse
+
+
+¶
+ Bases: FixedNode
A node representing an if-else clause.
+ + + + + + + + + +
apply_function_to_operands(function)
+
+¶
replace_operands_using_function(function)
+
+¶
evaluate(actual_inputs)
+
+¶
clear_cache(already_cleared)
+
+¶Clears any cached values of the node and any of its operands.
+ +
to_graph(graph_builder)
+
+¶Adds this node to the graph as well as its edges.
+ + +Returns:
+int
+ –
+ The identifier of this Node
in the DotFile
.
eliminate_common_subexpressions(terms)
+
+¶Eliminates duplicate subexpressions that are equivalent (as defined by a node's __eq__
and __hash__
method).
Returns:
+Node
+ –
+ A Node
that must replace the previous expression.
count_parents()
+
+¶Counts the total number of nodes in this subcircuit.
+ +
reset_parent_count()
+
+¶Resets the cached number of nodes in this subcircuit to 0.
+ +
arithmetize(strategy)
+
+¶
arithmetize_depth_aware(cost_of_squaring)
+
+¶
to_arithmetic()
+
+¶Outputs this node's equivalent ArithmeticNode. Errors if this node does not have a direct arithmetic equivalent.
+ + +Raises:
+Exception
+ –
+ If there is no direct arithmetic equivalent.
+
add(other, flatten=True)
+
+¶Performs a summation between self
and other
, possibly flattening any sums.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Sum
node or a Constant
representing self & other.
__add__(other)
+
+¶
__radd__(other)
+
+¶
mul(other, flatten=True)
+
+¶Performs a multiplication between self
and other
, possibly flattening any products.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Product
node or a Constant
representing self & other.
__mul__(other)
+
+¶
bool_or(other, flatten=True)
+
+¶Performs an OR operation between self
and other
, possibly flattening the result into an OR operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened Or
node or a Constant
representing self & other.
__or__(other)
+
+¶
bool_and(other, flatten=True)
+
+¶Performs an AND operation between self
and other
, possibly flattening the result into an AND operation between many operands.
It is possible to disable flattening by setting flatten=False
.
Returns:
+Node
+ –
+ A possibly flattened And
node or a Constant
representing self & other.
__and__(other)
+
+¶
__lt__(other)
+
+¶
__gt__(other)
+
+¶
__le__(other)
+
+¶
__ge__(other)
+
+¶
__neg__()
+
+¶
__invert__()
+
+¶
__pow__(other)
+
+¶
__sub__(other)
+
+¶
__rsub__(other)
+
+¶
__eq__(other)
+
+¶
__init__(condition, positive, negative, gf)
+
+¶Initialize an if-else node: If condition evaluates to true, then it outputs positive, otherwise it outputs negative.
+ +
__hash__()
+
+¶
is_equivalent(other)
+
+¶
operands()
+
+¶
set_operands(operands)
+
+¶
operation(operands)
+
+¶Warning
+In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.
+If you are using depth-aware arithmetization, you will find that the compiler does not output one arithmetic circuit. +Instead, it outputs a Pareto front, which represents the best circuits that it could generate trading off two metrics: +The multiplicative depth and the multiplicative size/cost. +This page briefly explains the API for interfacing with these Pareto fronts.
+
ParetoFront
+
+
+¶
+ Bases: ABC
Abstract base class for ParetoFronts.
+One objective is to minimize the multiplicative depth, while the other objective is minimizing some value, such as the multiplicative size or cost.
+ + + + + + + + + +
__init__()
+
+¶Initialize an empty ParetoFront.
+ +
from_node(node, depth=None, value=None)
+
+
+ classmethod
+
+
+¶Initialize a ParetoFront
with one node in it.
Returns:
+ParetoFront
+ –
+ New ParetoFront
.
from_leaf(leaf)
+
+
+ classmethod
+
+
+¶Initialize a ParetoFront
with one leaf node in it.
Returns:
+ParetoFront
+ –
+ New ParetoFront
.
add(node, depth=None, value=None)
+
+¶Adds the given Node
to the ParetoFront
by computing its multiplicative depth and value.
Alternatively, the user can supply an unchecked depth
and value
so that these values do not have to be (re)computed.
Returns:
+True
if and only if the node was inserted into the ParetoFront (so it was in some way better than the current Nodes
).
add_leaf(leaf)
+
+¶Add a leaf node to this ParetoFront
.
add_front(front)
+
+¶Add all elements from front
to self
.
__iter__()
+
+¶
get_smallest_at_depth(max_depth)
+
+¶Returns the circuit with the smallest value that has at most depth max_depth
.
is_empty()
+
+¶Returns whether the front is empty.
+ +
get_lowest_value()
+
+¶Returns the value (size or cost) of the Node with the highest depth, and therefore the lowest value.
+ +