torus/docs/dev/api/README.md

API Overview

Modules

• torus.compiler: Compiler submodule.
• torus.compiler.compilation_context: CompilationContext.
• torus.compiler.compilation_feedback: Compilation feedback.
• torus.compiler.tfhers_int: Import and export TFHErs integers into Torus.
• torus.compiler.utils: Common utils for the compiler submodule.
• torus.fhe: Torus.
• torus.fhe.compilation: Glue the compilation process together.
• torus.fhe.compilation.artifacts: Declaration of DebugArtifacts class.
• torus.fhe.compilation.circuit: Declaration of Circuit class.
• torus.fhe.compilation.client: Declaration of Client class.
• torus.fhe.compilation.compiler: Declaration of Compiler class.
• torus.fhe.compilation.composition: Declaration of classes related to composition.
• torus.fhe.compilation.configuration: Declaration of Configuration class.
• torus.fhe.compilation.decorators: Declaration of circuit and compiler decorators.
• torus.fhe.compilation.evaluation_keys: Declaration of EvaluationKeys.
• torus.fhe.compilation.keys: Declaration of Keys class.
• torus.fhe.compilation.module: Declaration of FheModule classes.
• torus.fhe.compilation.module_compiler: Declaration of MultiCompiler class.
• torus.fhe.compilation.server: Declaration of Server class.
• torus.fhe.compilation.specs: Declaration of ClientSpecs class.
• torus.fhe.compilation.status: Declaration of EncryptionStatus class.
• torus.fhe.compilation.utils: Declaration of various functions and constants related to compilation.
• torus.fhe.compilation.value: Declaration of Value class.
• torus.fhe.compilation.wiring: Declaration of wiring related class.
• torus.fhe.dtypes: Define available data types and their semantics.
• torus.fhe.dtypes.base: Declaration of BaseDataType abstract class.
• torus.fhe.dtypes.float: Declaration of Float class.
• torus.fhe.dtypes.integer: Declaration of Integer class.
• torus.fhe.dtypes.utils: Declaration of various functions and constants related to data types.
• torus.fhe.extensions: Provide additional features that are not present in numpy.
• torus.fhe.extensions.array: Declaration of array function, to simplify creation of encrypted arrays.
• torus.fhe.extensions.bits: Bit extraction extensions.
• torus.fhe.extensions.constant: Declaration of constant functions, to allow server side trivial encryption.
• torus.fhe.extensions.convolution: Tracing and evaluation of convolution.
• torus.fhe.extensions.hint: Declaration of hinting extensions, to provide more information to Torus.
• torus.fhe.extensions.identity: Declaration of identity extension.
• torus.fhe.extensions.maxpool: Tracing and evaluation of maxpool.
• torus.fhe.extensions.multivariate: Declaration of multivariate extension.
• torus.fhe.extensions.ones: Declaration of ones and one functions, to simplify creation of encrypted ones.
• torus.fhe.extensions.relu: Declaration of relu extension.
• torus.fhe.extensions.round_bit_pattern: Declaration of round_bit_pattern function, to provide an interface for rounded table lookups.
• torus.fhe.extensions.table: Declaration of LookupTable class.
• torus.fhe.extensions.tag: Declaration of tag context manager, to allow tagging certain nodes.
• torus.fhe.extensions.truncate_bit_pattern: Declaration of truncate_bit_pattern extension.
• torus.fhe.extensions.univariate: Declaration of univariate function.
• torus.fhe.extensions.zeros: Declaration of zeros and zero functions, to simplify creation of encrypted zeros.
• torus.fhe.internal.
• torus.fhe.internal.utils: Declaration of various functions and constants related to the entire project.
• torus.fhe.mlir: Provide computation graph to mlir functionality.
• torus.fhe.mlir.context: Declaration of Context class.
• torus.fhe.mlir.conversion: Declaration of ConversionType and Conversion classes.
• torus.fhe.mlir.converter: Declaration of Converter class.
• torus.fhe.mlir.processors: All graph processors.
• torus.fhe.mlir.processors.assign_bit_widths: Declaration of AssignBitWidths graph processor.
• torus.fhe.mlir.processors.assign_node_ids: Declaration of AssignNodeIds graph processor.
• torus.fhe.mlir.processors.check_integer_only: Declaration of CheckIntegerOnly graph processor.
• torus.fhe.mlir.processors.process_rounding: Declaration of ProcessRounding graph processor.
• torus.fhe.mlir.utils: Declaration of various functions and constants related to MLIR conversion.
• torus.fhe.representation: Define structures used to represent computation.
• torus.fhe.representation.evaluator: Declaration of various Evaluator classes, to make graphs picklable.
• torus.fhe.representation.graph: Declaration of Graph class.
• torus.fhe.representation.node: Declaration of Node class.
• torus.fhe.representation.operation: Declaration of Operation enum.
• torus.fhe.representation.utils: Declaration of various functions and constants related to representation of computation.
• torus.fhe.tfhers: tfhers module to represent, and compute on tfhers integer values.
• torus.fhe.tfhers.bridge: Declaration of tfhers.Bridge class.
• torus.fhe.tfhers.dtypes: Declaration of TFHERSIntegerType class.
• torus.fhe.tfhers.specs: Lux-FHE client specs.
• torus.fhe.tfhers.tracing: Tracing of tfhers operations.
• torus.fhe.tfhers.values: Declaration of TFHERSInteger which wraps values as being of tfhers types.
• torus.fhe.tracing: Provide function to computation graph functionality.
• torus.fhe.tracing.tracer: Declaration of Tracer class.
• torus.fhe.tracing.typing: Declaration of type annotation.
• torus.fhe.values: Define the available values and their semantics.
• torus.fhe.values.scalar: Declaration of ClearScalar and EncryptedScalar wrappers.
• torus.fhe.values.tensor: Declaration of ClearTensor and EncryptedTensor wrappers.
• torus.fhe.values.value_description: Declaration of ValueDescription class.
• torus.fhe.version: Version of the project, which is updated automatically by the CI right before releasing.
• torus.lang: Toruslang python module
• torus.lang.dialects
• torus.lang.dialects.fhe: FHE dialect module
• torus.lang.dialects.fhelinalg: FHELinalg dialect module
• torus.lang.dialects.tracing: Tracing dialect module

Classes

• compiler.KeysetRestrictionHandler: Handler to serialize and deserialize keyset restrictions
• compiler.RangeRestrictionHandler: Handler to serialize and deserialize range restrictions
• compilation_context.CompilationContext: Compilation context.
• compilation_feedback.MoreCircuitCompilationFeedback: Helper class for compilation feedback.
• tfhers_int.TfhersExporter: A helper class to import and export TFHErs big integers.
• artifacts.DebugArtifacts: DebugArtifacts class, to export information about the compilation process for single function.
• artifacts.DebugManager: A debug manager, allowing streamlined debugging.
• artifacts.FunctionDebugArtifacts: An object containing debug artifacts for a certain function in an fhe module.
• artifacts.ModuleDebugArtifacts: An object containing debug artifacts for an fhe module.
• circuit.Circuit: Circuit class, to combine computation graph, mlir, client and server into a single object.
• client.Client: Client class, which can be used to manage keys, encrypt arguments and decrypt results.
• compiler.Compiler: Compiler class, to glue the compilation pipeline.
• composition.CompositionClause: A raw composition clause.
• composition.CompositionPolicy: A protocol for composition policies.
• composition.CompositionRule: A raw composition rule.
• configuration.ApproximateRoundingConfig: Controls the behavior of approximate rounding.
• configuration.BitwiseStrategy: BitwiseStrategy, to specify implementation preference for bitwise operations.
• configuration.ComparisonStrategy: ComparisonStrategy, to specify implementation preference for comparisons.
• configuration.Configuration: Configuration class, to allow the compilation process to be customized.
• configuration.Exactness.
• configuration.MinMaxStrategy: MinMaxStrategy, to specify implementation preference for minimum and maximum operations.
• configuration.MultiParameterStrategy: MultiParamStrategy, to set optimization strategy for multi-parameter.
• configuration.MultivariateStrategy: MultivariateStrategy, to specify implementation preference for multivariate operations.
• configuration.ParameterSelectionStrategy: ParameterSelectionStrategy, to set optimization strategy.
• configuration.SecurityLevel: Security level used to optimize the circuit parameters.
• decorators.Compilable: Compilable class, to wrap a function and provide methods to trace and compile it.
• evaluation_keys.EvaluationKeys: EvaluationKeys required for execution.
• keys.Keys: Keys class, to manage generate/reuse keys.
• module.ExecutionRt: Runtime object class for execution.
• module.FheFunction: Fhe function class, allowing to run or simulate one function of an fhe module.
• module.FheModule: Fhe module class, to combine computation graphs, mlir, runtime objects into a single object.
• module.SimulationRt: Runtime object class for simulation.
• module_compiler.FunctionDef: An object representing the definition of a function as used in an fhe module.
• module_compiler.ModuleCompiler: Compiler class for multiple functions, to glue the compilation pipeline.
• server.Server: Server class, which can be used to perform homomorphic computation.
• specs.ClientSpecs: ClientSpecs class, to create Client objects.
• status.EncryptionStatus: EncryptionStatus enum, to represent encryption status of parameters.
• utils.Lazy: A lazyly initialized value.
• value.Value: A public value object that can be sent between client and server.
• wiring.AllComposable: Composition policy that allows to forward any output of the module to any of its input.
• wiring.AllInputs: All the encrypted inputs of a given function of a module.
• wiring.AllOutputs: All the encrypted outputs of a given function of a module.
• wiring.Input: The input of a given function of a module.
• wiring.NotComposable: Composition policy that does not allow the forwarding of any output to any input.
• wiring.Output: The output of a given function of a module.
• wiring.TracedOutput: A wrapper type used to trace wiring.
• wiring.Wire: A forwarding rule between an output and an input.
• wiring.WireInput: A protocol for wire inputs.
• wiring.WireOutput: A protocol for wire outputs.
• wiring.WireTracingContextManager: A context manager returned by the wire_pipeline method.
• wiring.Wired: Composition policy which allows the forwarding of certain outputs to certain inputs.
• base.BaseDataType: BaseDataType abstract class, to form a basis for data types.
• float.Float: Float class, to represent floating point numbers.
• integer.Integer: Integer class, to represent integers.
• bits.Bits: Bits class, to provide indexing into the bits of integers.
• round_bit_pattern.Adjusting: Adjusting class, to be used as early stop signal during adjustment.
• round_bit_pattern.AutoRounder: AutoRounder class, to optimize for number of msbs to keep during round bit pattern operation.
• table.LookupTable: LookupTable class, to provide a way to do direct table lookups.
• truncate_bit_pattern.Adjusting: Adjusting class, to be used as early stop signal during adjustment.
• truncate_bit_pattern.AutoTruncator: AutoTruncator class, to optimize for the number of msbs to keep during truncate operation.
• context.Context: Context class, to perform operations on conversions.
• conversion.Conversion: Conversion class, to store MLIR operations with additional information.
• conversion.ConversionType: ConversionType class, to make it easier to work with MLIR types.
• converter.Converter: Converter class, to convert a computation graph to MLIR.
• assign_bit_widths.AdditionalConstraints: AdditionalConstraints class to customize bit-width assignment step easily.
• assign_bit_widths.AssignBitWidths: AssignBitWidths graph processor, to assign proper bit-widths to be compatible with FHE.
• assign_node_ids.AssignNodeIds to node properties.
• check_integer_only.CheckIntegerOnly: CheckIntegerOnly graph processor, to make sure the graph only contains integer nodes.
• process_rounding.ProcessRounding: ProcessRounding graph processor, to analyze rounding and support regular operations on it.
• utils.Comparison: Comparison enum, to store the result comparison in 2-bits as there are three possible outcomes.
• utils.HashableNdarray: HashableNdarray class, to use numpy arrays in dictionaries.
• evaluator.ConstantEvaluator: ConstantEvaluator class, to evaluate Operation.Constant nodes.
• evaluator.GenericEvaluator: GenericEvaluator class, to evaluate Operation.Generic nodes.
• evaluator.GenericTupleEvaluator: GenericEvaluator class, to evaluate Operation.Generic nodes where args are packed in a tuple.
• evaluator.InputEvaluator: InputEvaluator class, to evaluate Operation.Input nodes.
• graph.Graph: Graph class, to represent computation graphs.
• graph.GraphProcessor: GraphProcessor base class, to define the API for a graph processing pipeline.
• graph.MultiGraphProcessor: MultiGraphProcessor base class, to define the API for a multiple graph processing pipeline.
• node.Node: Node class, to represent computation in a computation graph.
• operation.Operation: Operation enum, to distinguish nodes within a computation graph.
• bridge.Bridge: TFHErs Bridge extend a Client with TFHErs functionalities.
• dtypes.CryptoParams: Crypto parameters used for a tfhers integer.
• dtypes.EncryptionKeyChoice: TFHErs key choice: big or small.
• dtypes.TFHERSIntegerType to represent tfhers integer types.
• specs.TFHERSClientSpecs: Lux-FHE client specs.
• values.TFHERSInteger into typed values, using tfhers types.
• tracer.Annotation: Base annotation for direct definition.
• tracer.ScalarAnnotation: Base scalar annotation for direct definition.
• tracer.TensorAnnotation: Base tensor annotation for direct definition.
• tracer.Tracer: Tracer class, to create computation graphs from python functions.
• typing.f32: Scalar f32 annotation.
• typing.f64: Scalar f64 annotation.
• typing.int1: Scalar int1 annotation.
• typing.int10: Scalar int10 annotation.
• typing.int11: Scalar int11 annotation.
• typing.int12: Scalar int12 annotation.
• typing.int13: Scalar int13 annotation.
• typing.int14: Scalar int14 annotation.
• typing.int15: Scalar int15 annotation.
• typing.int16: Scalar int16 annotation.
• typing.int17: Scalar int17 annotation.
• typing.int18: Scalar int18 annotation.
• typing.int19: Scalar int19 annotation.
• typing.int2: Scalar int2 annotation.
• typing.int20: Scalar int20 annotation.
• typing.int21: Scalar int21 annotation.
• typing.int22: Scalar int22 annotation.
• typing.int23: Scalar int23 annotation.
• typing.int24: Scalar int24 annotation.
• typing.int25: Scalar int25 annotation.
• typing.int26: Scalar int26 annotation.
• typing.int27: Scalar int27 annotation.
• typing.int28: Scalar int28 annotation.
• typing.int29: Scalar int29 annotation.
• typing.int3: Scalar int3 annotation.
• typing.int30: Scalar int30 annotation.
• typing.int31: Scalar int31 annotation.
• typing.int32: Scalar int32 annotation.
• typing.int33: Scalar int33 annotation.
• typing.int34: Scalar int34 annotation.
• typing.int35: Scalar int35 annotation.
• typing.int36: Scalar int36 annotation.
• typing.int37: Scalar int37 annotation.
• typing.int38: Scalar int38 annotation.
• typing.int39: Scalar int39 annotation.
• typing.int4: Scalar int4 annotation.
• typing.int40: Scalar int40 annotation.
• typing.int41: Scalar int41 annotation.
• typing.int42: Scalar int42 annotation.
• typing.int43: Scalar int43 annotation.
• typing.int44: Scalar int44 annotation.
• typing.int45: Scalar int45 annotation.
• typing.int46: Scalar int46 annotation.
• typing.int47: Scalar int47 annotation.
• typing.int48: Scalar int48 annotation.
• typing.int49: Scalar int49 annotation.
• typing.int5: Scalar int5 annotation.
• typing.int50: Scalar int50 annotation.
• typing.int51: Scalar int51 annotation.
• typing.int52: Scalar int52 annotation.
• typing.int53: Scalar int53 annotation.
• typing.int54: Scalar int54 annotation.
• typing.int55: Scalar int55 annotation.
• typing.int56: Scalar int56 annotation.
• typing.int57: Scalar int57 annotation.
• typing.int58: Scalar int58 annotation.
• typing.int59: Scalar int59 annotation.
• typing.int6: Scalar int6 annotation.
• typing.int60: Scalar int60 annotation.
• typing.int61: Scalar int61 annotation.
• typing.int62: Scalar int62 annotation.
• typing.int63: Scalar int63 annotation.
• typing.int64: Scalar int64 annotation.
• typing.int7: Scalar int7 annotation.
• typing.int8: Scalar int8 annotation.
• typing.int9: Scalar int9 annotation.
• typing.tensor: Tensor annotation.
• typing.uint1: Scalar uint1 annotation.
• typing.uint10: Scalar uint10 annotation.
• typing.uint11: Scalar uint11 annotation.
• typing.uint12: Scalar uint12 annotation.
• typing.uint13: Scalar uint13 annotation.
• typing.uint14: Scalar uint14 annotation.
• typing.uint15: Scalar uint15 annotation.
• typing.uint16: Scalar uint16 annotation.
• typing.uint17: Scalar uint17 annotation.
• typing.uint18: Scalar uint18 annotation.
• typing.uint19: Scalar uint19 annotation.
• typing.uint2: Scalar uint2 annotation.
• typing.uint20: Scalar uint20 annotation.
• typing.uint21: Scalar uint21 annotation.
• typing.uint22: Scalar uint22 annotation.
• typing.uint23: Scalar uint23 annotation.
• typing.uint24: Scalar uint24 annotation.
• typing.uint25: Scalar uint25 annotation.
• typing.uint26: Scalar uint26 annotation.
• typing.uint27: Scalar uint27 annotation.
• typing.uint28: Scalar uint28 annotation.
• typing.uint29: Scalar uint29 annotation.
• typing.uint3: Scalar uint3 annotation.
• typing.uint30: Scalar uint30 annotation.
• typing.uint31: Scalar uint31 annotation.
• typing.uint32: Scalar uint32 annotation.
• typing.uint33: Scalar uint33 annotation.
• typing.uint34: Scalar uint34 annotation.
• typing.uint35: Scalar uint35 annotation.
• typing.uint36: Scalar uint36 annotation.
• typing.uint37: Scalar uint37 annotation.
• typing.uint38: Scalar uint38 annotation.
• typing.uint39: Scalar uint39 annotation.
• typing.uint4: Scalar uint4 annotation.
• typing.uint40: Scalar uint40 annotation.
• typing.uint41: Scalar uint41 annotation.
• typing.uint42: Scalar uint42 annotation.
• typing.uint43: Scalar uint43 annotation.
• typing.uint44: Scalar uint44 annotation.
• typing.uint45: Scalar uint45 annotation.
• typing.uint46: Scalar uint46 annotation.
• typing.uint47: Scalar uint47 annotation.
• typing.uint48: Scalar uint48 annotation.
• typing.uint49: Scalar uint49 annotation.
• typing.uint5: Scalar uint5 annotation.
• typing.uint50: Scalar uint50 annotation.
• typing.uint51: Scalar uint51 annotation.
• typing.uint52: Scalar uint52 annotation.
• typing.uint53: Scalar uint53 annotation.
• typing.uint54: Scalar uint54 annotation.
• typing.uint55: Scalar uint55 annotation.
• typing.uint56: Scalar uint56 annotation.
• typing.uint57: Scalar uint57 annotation.
• typing.uint58: Scalar uint58 annotation.
• typing.uint59: Scalar uint59 annotation.
• typing.uint6: Scalar uint6 annotation.
• typing.uint60: Scalar uint60 annotation.
• typing.uint61: Scalar uint61 annotation.
• typing.uint62: Scalar uint62 annotation.
• typing.uint63: Scalar uint63 annotation.
• typing.uint64: Scalar uint64 annotation.
• typing.uint7: Scalar uint7 annotation.
• typing.uint8: Scalar uint8 annotation.
• typing.uint9: Scalar uint9 annotation.
• value_description.ValueDescription: ValueDescription class, to combine data type, shape, and encryption status into a single object.

Functions

• compiler.check_gpu_available: Check whether a CUDA device is available and online.
• compiler.check_gpu_enabled: Check whether the compiler and runtime support GPU offloading.
• compiler.init_dfr: Initialize dataflow parallelization.
• compiler.round_trip: Parse the MLIR input, then return it back.
• compilation_feedback.tag_from_location: Extract tag of the operation from its location.
• utils.lookup_runtime_lib: Try to find the absolute path to the runtime library.
• decorators.circuit: Provide a direct interface for compilation of single circuit programs.
• decorators.compiler: Provide an easy interface for the compilation of single-circuit programs.
• decorators.function: Provide an easy interface to define a function within an fhe module.
• decorators.module: Provide an easy interface for the compilation of multi functions modules.
• utils.add_nodes_from_to: Add nodes from from_nodes to to_nodes, to all_nodes.
• utils.check_subgraph_fusibility: Determine if a subgraph can be fused.
• utils.convert_subgraph_to_subgraph_node: Convert a subgraph to Operation.Generic node.
• utils.find_closest_integer_output_nodes: Find the closest upstream integer output nodes to a set of start nodes in a graph.
• utils.find_float_subgraph_with_unique_terminal_node: Find a subgraph with float computations that end with an integer output.
• utils.find_single_lca: Find the single lowest common ancestor of a list of nodes.
• utils.find_tlu_subgraph_with_multiple_variable_inputs_that_has_a_single_common_ancestor: Find a subgraph with a tlu computation that has multiple variable inputs where all variable inputs share a common ancestor.
• utils.friendly_type_format: Convert a type to a string. Remove package name and class/type keywords.
• utils.fuse: Fuse appropriate subgraphs in a graph to a single Operation.Generic node.
• utils.get_terminal_size: Get the terminal size.
• utils.inputset: Generate a random inputset.
• utils.is_single_common_ancestor: Determine if a node is the single common ancestor of a list of nodes.
• utils.validate_input_args: Validate input arguments.
• utils.combine_dtypes: Get the 'BaseDataType' that can represent a set of 'BaseDataType's.
• array.array: Create an encrypted array from either encrypted or clear values.
• bits.bits: Extract bits of integers.
• constant.constant: Trivial encryption of a cleartext value.
• convolution.conv: Trace and evaluate convolution operations.
• hint.hint: Hint the compilation process about properties of a value.
• identity.identity: Apply identity function to x.
• identity.refresh: Refresh x.
• maxpool.maxpool: Evaluate or trace MaxPool operation.
• multivariate.multivariate: Wrap a multivariate function so that it is traced into a single generic node.
• ones.one: Create an encrypted scalar with the value of one.
• ones.ones: Create an encrypted array of ones.
• ones.ones_like: Create an encrypted array of ones with the same shape as another array.
• relu.relu: Rectified linear unit extension.
• round_bit_pattern.round_bit_pattern: Round the bit pattern of an integer.
• tag.tag: Introduce a new tag to the tag stack.
• truncate_bit_pattern.truncate_bit_pattern: Round the bit pattern of an integer.
• univariate.univariate: Wrap a univariate function so that it is traced into a single generic node.
• zeros.zero: Create an encrypted scalar with the value of zero.
• zeros.zeros: Create an encrypted array of zeros.
• zeros.zeros_like: Create an encrypted array of zeros with the same shape as another array.
• utils.assert_that: Assert a condition.
• utils.unreachable: Raise a RuntimeError to indicate unreachable code is entered.
• utils.construct_deduplicated_tables: Construct lookup tables for each cell of the input for an Operation.Generic node.
• utils.construct_table: Construct the lookup table for an Operation.Generic node.
• utils.construct_table_multivariate: Construct the lookup table for a multivariate node.
• utils.flood_replace_none_values: Use flooding algorithm to replace None values.
• utils.format_constant: Get the textual representation of a constant.
• utils.format_indexing_element: Format an indexing element.
• tfhers.get_type_from_params: Get a Lux-FHE integer type from Lux-FHE parameters in JSON format.
• tfhers.get_type_from_params_dict: Get a Lux-FHE integer type from Lux-FHE parameters in JSON format.
• bridge.new_bridge: Create a TFHErs bridge from a circuit or module or client.
• tracing.from_native: Convert a Torus integer to the tfhers representation.
• tracing.to_native: Convert a tfhers integer to the Torus representation.
• scalar.clear_scalar_builder: Build a clear scalar value.
• scalar.encrypted_scalar_builder: Build an encrypted scalar value.
• scalar.clear_scalar_builder: Build a clear scalar value.
• scalar.encrypted_scalar_builder: Build an encrypted scalar value.
• tensor.clear_tensor_builder: Build a clear tensor value.
• tensor.encrypted_tensor_builder: Build an encrypted tensor value.
• tensor.clear_tensor_builder: Build a clear tensor value.
• tensor.encrypted_tensor_builder: Build an encrypted tensor value.