circuitry module

Embedded domain-specific combinator library for assembling abstract definitions of logical circuits and for automatically synthesizing circuits from those definitions.

This library makes it possible both to construct circuits programmatically (see the documentation for the bit class) and to synthesize circuits in an automated manner from Python function definitions (see the documentation for the synthesize function).

class circuitry.circuitry.bit(value: int, gate: Optional[gate] = None)[source]

Bases: object

Class for representing an abstract bit. Such a bit can be interpreted concretely as a value, but it is also used to keep track of relationships between operators and to represent the individual wires within a circuit that is programmatically built up from gates that correspond to those operators.

The documentation for this class describes how circuits can be synthesized programmatically using the methods made available by this class. Consult the documentation for the synthesize function to learn how circuits can be synthesized automatically from Python function definitions.

When constructing a circuit programmatically, it is first necessary to introduce a new circuit object and to designate this object as the circuit that is being constructed.

>>> c = circuit()
>>> bit.circuit(c)

Subsequently, it is possible to instantiate subclasses of bit that serve specific roles (such as input, which represents an input value into the overall circuit being constructed). An operator method such as bit.and_ can be used to operate on bit instances (and, at the same time to introduce a gate into the circuit).

>>> b = output(input(1).and_(input(1)))

At this point, constructed circuit can be retrieved and evaluated on a vector of bit values (wherein each value is represented using the integer 0 or the integer 1).

>>> b.value == bit.circuit().evaluate([1, 1])[0]
True

It is possible to add custom hook functions that are applied whenever an operator is introduced using the bit.hook_operation method.

>>> def make_hook_that_prints_created_gates(bit_):
...     def hook(o, v, *args):
...         print('created gate with operation "' + o.name() + '"')
...         return bit_.constructor(*args)(v, bit_.gate(o, [a.gate for a in args]))
...     return hook
>>> bit.hook_operation(make_hook_that_prints_created_gates(bit))
>>> bit.circuit(circuit())
>>> b = output(input(0).and_(input(1)).not_())
created gate with operation "and"
created gate with operation "not"

Note that a hook must be removed if its effects are not desired when subsequent circuits are constructed.

>>> bit.hook_operation()

static circuit(circuit: Optional[circuit.circuit.circuit] = None) → Optional[circuit.circuit.circuit][source]

Designate the circuit object that is under construction. Any invocation of the bit constructor adds a gate to the circuit designated using this method.

>>> c = circuit()
>>> bit.circuit(c)
>>> b = output(input(1).and_(input(1)))
>>> b.value == bit.circuit().evaluate([1, 1])[0]
True

Invoking this method with no argument retrieves and removes the circuit object (leaving no designated circuit object). Note that because of the invocation of this method at the end of the above example, the invocation below returns None.

>>> bit.circuit() is None
True

static hook_operation(hook: Optional[Callable] = None)[source]

Assign a function that is invoked whenever the bit.operation method is used to create a new instance of bit.

>>> def make_hook_that_prints_created_gates(bit_):
...     def hook(o, v, *args):
...         print('created gate with operation "' + o.name() + '"')
...         return bit_.constructor(*args)(v, bit_.gate(o, [a.gate for a in args]))
...     return hook
>>> bit.hook_operation(make_hook_that_prints_created_gates(bit))
>>> bit.circuit(circuit())
>>> b = output(input(0).and_(input(1)).not_())
created gate with operation "and"
created gate with operation "not"
>>> b.value == bit.circuit().evaluate([0, 0])[0]
True

If a hook function returns None, then the default instance of bit is returned when an operation is applied.

>>> bit.hook_operation(lambda o, v, *args: None)
>>> bit.circuit(circuit())
>>> b = output(input(1).and_(input(1)))
>>> b.value == bit.circuit().evaluate([1, 1])[0]
True

It is only possible to assign one hook function at a time. A hook must be removed if its effects are not desired when subsequent circuits are constructed.

>>> bit.hook_operation()

static operation(o: Callable, *args) → circuitry.circuitry.bit[source]

Apply the supplied operation method to zero or more bit arguments. Gate operations are represented using instances of the logical class exported by the logical library. This module indirectly imports the logical class via the op synonym defined in the circuit library, enabling the more concise syntax used in the example below.

>>> bit.circuit(circuit())
>>> b = output(bit.operation(op.and_, input(1), input(1)))
>>> b.value == bit.circuit().evaluate([1, 1])[0]
True

Arguments that are instances of output are not permitted.

>>> bit.circuit(circuit())
>>> b0 = output(input(0).not_())
>>> b1 = b0.not_()
Traceback (most recent call last):
  ...
TypeError: cannot supply an output as an argument to an operation
>>> _ = bit.circuit() # Remove designated circuit.

static constructor(b1: Optional[circuitry.circuitry.bit] = None, b2: Optional[circuitry.circuitry.bit] = None) → type[source]: Return the constructor to use for instantiating a bit object. This method is used by the bit.operation and bits.from_byte methods. It is provided primarily to aid in the implementation of custom hooks that can be set using the bit.hook_operation method.

static gate(operation: op, igs: Sequence[gate]) → Optional[gate][source]

Add a gate to the designated circuit object that is under construction. This method is primarily provided to aid in the implementation of custom hooks that can be set using the bit.hook_operation method. Gate operations are represented using instances of the logical class exported by the logical library (which is indirectly imported into this module as the op synonym from the circuit library).

>>> def make_hook(bit_):
...     def hook(o, v, *args):
...         return bit_.constructor(*args)(v, bit_.gate(o, [a.gate for a in args]))
...     return hook
>>> bit.hook_operation(make_hook(bit))
>>> bit.circuit(circuit())
>>> b = output(input(0).and_(input(0)))
>>> b.value == bit.circuit().evaluate([0, 0])[0]
True

__int__() → int[source]

Convert this bit instance into the integer representation of its value.

>>> int(bit(1))
1

id_() → circuitry.circuitry.bit[source]

Logical operation for an individual bit instance.

>>> results = []
>>> for x in [0, 1]:
...     bit.circuit(circuit())
...     b = output(input(x).id_())
...     results.append(int(b) == bit.circuit().evaluate([x])[0])
>>> all(results)
True

not_() → circuitry.circuitry.bit[source]

Logical operation for an individual bit instance.

>>> results = []
>>> for x in [0, 1]:
...     bit.circuit(circuit())
...     b = output(input(x).not_())
...     results.append(int(b) == bit.circuit().evaluate([x])[0])
>>> all(results)
True

__invert__() → circuitry.circuitry.bit[source]

Logical operation for an individual bit instance.

>>> results = []
>>> for x in [0, 1]:
...     bit.circuit(circuit())
...     b = output(~input(x))
...     results.append(int(b) == bit.circuit().evaluate([x])[0])
>>> all(results)
True

__rsub__(other: circuitry.circuitry.bit) → circuitry.circuitry.bit[source]

Arithmetic operation involving an individual bit instance that is often used to represent the logical negation operation. This method is provided primarily as a convenience enabling use of the syntax 1 - b to represent logical negation of a bit value b; it does not enable subtraction of one bit instance from another.

>>> results = []
>>> for x in [0, 1]:
...     bit.circuit(circuit())
...     b = output(1 - input(x))
...     results.append(int(b) == bit.circuit().evaluate([x])[0])
>>> all(results)
True
>>> 2 - input(0)
Traceback (most recent call last):
  ...
ValueError: can only subtract a bit from the integer 1

and_(other: circuitry.circuitry.bit) → circuitry.circuitry.bit[source]