Circuits API

Warning

In this version of Oraqle, the API is still prone to changes. Paths and names can change between any version.

High-level circuits

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.

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.

Arithmetic circuits

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.

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).