Combinational Logic

Combinational Logic#

Data Types#

class seqlogic.Bits#

Sequence of bits.

A bit is a 4-state logical value in the set {0, 1, X, -}:

  • 0 is Boolean zero or “False”

  • 1 is Boolean one or “True”

  • X is an uninitialized or metastable value

  • - is a “don’t care” value

The values 0 and 1 are “known”. The values X and - are “unknown”.

Bits is the base class for a family of hardware-oriented data types. All Bits objects have a size attribute. Shaped subclasses (Empty, Scalar, Vector, Array) have a shape attribute. Composite subclasses (Struct, Union) have user-defined attributes.

Bits does NOT implement the Python Sequence protocol.

Children:

              Bits
                |
  +------+------+-----+------+-----+
  |      |      |     |      |     |
Empty Scalar Vector Array Struct Union
                |
              Enum

Do NOT construct a Bits object directly. Use one of the factory functions:

  • bits

  • stack

  • u2bv

  • i2bv

property size#

Number of bits

classmethod cast(x: Bits) → Bits#

Convert Bits object to an instance of this class.

For example, to cast an Array[2,2] to a Vector[4]:

>>> x = bits(["2b00", "2b11"])
>>> Vector[4].cast(x)
bits("4b1100")
Raises:

TypeError – Object size does not match this class size.

classmethod xes() → Bits#

Return an instance filled with X bits.

For example:

>>> Vector[4].xes()
bits("4bXXXX")
classmethod zeros() → Bits#

Return an instance filled with 0 bits.

For example:

>>> Vector[4].zeros()
bits("4b0000")
classmethod ones() → Bits#

Return an instance filled with 1 bits.

For example:

>>> Vector[4].ones()
bits("4b1111")
classmethod dcs() → Bits#

Return an instance filled with - bits.

For example:

>>> Vector[4].dcs()
bits("4b----")
classmethod xprop(sel: Bits) → Bits#

Propagate X in a wildcard pattern (default case).

If sel contains an X, propagate X. Otherwise, treat as a “don’t care”, and propagate -.

For example:

>>> def f(x: Vector[1]) -> Vector[1]:
...     match x:
...         case "1b0":
...             return bits("1b1")
...         case _:
...             return Vector[1].xprop(x)

>>> f(bits("1b0"))  # Match!
bits("1b1")
>>> f(bits("1b1"))  # No match; No X prop
bits("1b-")
>>> f(bits("1bX"))  # No match; Yes X prop
bits("1bX")
Parameters:

sel – Bits object, typically a match subject

Returns:

Class instance filled with either - or X.

property data: tuple[int, int]#

Internal representation.

__bool__() → bool#

Convert to Python bool.

A Bits object is True if its value is known nonzero.

For example:

>>> bool(bits("1b0"))
False
>>> bool(bits("1b1"))
True
>>> bool(bits("4b0000"))
False
>>> bool(bits("4b1010"))
True

Warning

Be cautious about using any expression that might have an unknown value as the condition of a Python if or while statement.

Raises:

ValueError – Contains any unknown bits.

__int__() → int#

Convert to Python int.

Use two’s complement representation:

  • If most significant bit is 1, result will be negative.

  • If most significant bit is 0, result will be non-negative.

For example:

>>> int(bits("4b1010"))
-6
>>> int(bits("4b0101"))
5
Raises:

ValueError – Contains any unknown bits.

to_uint() → int#

Convert to unsigned integer.

Returns:

A non-negative int.

Raises:

ValueError – Contains any unknown bits.

to_int() → int#

Convert to signed integer.

Returns:

An int, from two’s complement encoding.

Raises:

ValueError – Contains any unknown bits.

count_xes() → int#

Return count of X bits.

count_zeros() → int#

Return count of of 0 bits.

count_ones() → int#

Return count of 1 bits.

count_dcs() → int#

Return count of - bits.

count_unknown() → int#

Return count of unknown bits.

onehot() → bool#

Return True if contains exactly one 1 bit.

onehot0() → bool#

Return True if contains at most one 1 bit.

has_x() → bool#

Return True if contains at least one X bit.

has_dc() → bool#

Return True if contains at least one - bit.

has_unknown() → bool#

Return True if contains at least one unknown bit.

class seqlogic.Empty(d0: int, d1: int)#

Null dimensional sequence of bits.

Degenerate form of a Vector resulting from an empty slice.

>>> from seqlogic import Vec
>>> Vec[0] is Empty
True

To get a handle to an Empty instance:

>>> empty = bits()

Empty implements Vector methods, but __getitem__ will always raise an exception:

>>> empty.size
0
>>> empty.shape
(0,)
>>> len(empty)
0
>>> empty[0]
Traceback (most recent call last):
    ...
IndexError: Expected index in [0, 0), got 0
class seqlogic.Scalar(d0: int, d1: int)#

Zero dimensional (scalar) sequence of bits.

Degenerate form of a Vector resulting from a one bit slice.

>>> from seqlogic import Vec
>>> Vec[1] is Scalar
True

To get a handle to a Scalar instance:

>>> f = bits("1b0")
>>> t = bits("1b1")
>>> x = bits("1bX")
>>> dc = bits("1b-")

For convenience, False and True also work:

>>> bits(False) is f and bits(True) is t
True

Scalar implements Vector methods, including __getitem__:

>>> t.size
1
>>> t.shape
(1,)
>>> len(t)
1
>>> t[0]
bits("1b1")
class seqlogic.Vector(d0: int, d1: int)#

One dimensional sequence of bits.

To create a Vector instance, use binary, decimal, or hexadecimal string literals:

>>> bits("4b1010")
bits("4b1010")
>>> bits("4d10")
bits("4b1010")
>>> bits("4ha")
bits("4b1010")

Vector implements size and shape attributes, as well as __len__ and __getitem__ methods:

>>> x = bits("8b1111_0000")
>>> x.size
8
>>> x.shape
(8,)
>>> len(x)
8
>>> x[3]
bits("1b0")
>>> x[4]
bits("1b1")
>>> x[2:6]
bits("4b1100")

A Vector may be converted into an equal-size multi-dimensional Array using the reshape method:

>>> x.reshape((2,4))
bits(["4b0000", "4b1111"])
class seqlogic.Array(d0: int, d1: int)#

Multi dimensional array of bits.

To create an Array instance, use the bits function:

>>> x = bits(["4b0100", "4b1110"])

Array implements size and shape attributes, and the __getitem__ method. Array does NOT implement a __len__ method.

>>> x.size
8
>>> x.shape
(2, 4)
>>> x[0]
bits("4b0100")
>>> x[1]
bits("4b1110")
>>> x[0,0]
bits("1b0")

An Array may be converted into an equal-size, multi-dimensional Array using the reshape method:

>>> x.reshape((4,2))
bits(["2b00", "2b01", "2b10", "2b11"])

An Array may be converted into an equal-size, one-dimensional Vector using the flatten method:

>>> x.flatten()
bits("8b1110_0100")
class seqlogic.Enum#

User-defined enumerated data type.

Define a type from a collection of unique constants.

Extend from Enum to define an enumeration:

>>> from seqlogic import Enum
>>> class Color(Enum):
...     RED = "2b00"
...     GREEN = "2b01"
...     BLUE = "2b10"

Enums behave like Vectors, but they have an extra name attribute:

>>> len(Color.RED)
2
>>> Color.RED[0]
bits("1b0")
>>> Color.RED == "2b00"
True
>>> Color.RED.name
'RED'

All Enums have X and DC attributes defined automatically:

>>> Color.X == "2bXX"
True
>>> Color.DC == "2b--"
True

To cast a Vec to an Enum, use the constructor:

>>> Color("2b00")
Color.RED

Values not included in the enumeration are allowed:

>>> Color("2b11")
Color("2b11")

To cast an Enum to a Vec, use the cast method:

>>> from seqlogic import Vec
>>> Vec[2].cast(Color.RED)
bits("2b00")
class seqlogic.Struct#

User defined struct data type.

Compose a type from a sequence of other types.

Extend from Struct to define a struct:

>>> from seqlogic import Vec
>>> class Pixel(Struct):
...     red: Vec[8]
...     green: Vec[8]
...     blue: Vec[8]

Use the new type’s constructor to create Struct instances:

>>> maize = Pixel(red="8hff", green="8hcb", blue="8h05")

Access individual fields using attributes:

>>> maize.red
bits("8b1111_1111")
>>> maize.green
bits("8b1100_1011")

Structs have a size, but no shape. They do NOT implement a __len__ method.

>>> Pixel.size
24

Struct slicing behaves like a Vector:

>>> maize[8:16] == maize.green
True
class seqlogic.Union#

User defined union data type.

Compose a type from the union of other types.

Extend from Union to define a struct:

>>> from seqlogic import Vec
>>> class Response(Union):
...     error: Vec[4]
...     data: Vec[8]

Use the new type’s constructor to create Union instances:

>>> rsp = Response("8h0f")

Access individual fields using attributes:

>>> rsp.error
bits("4b1111")
>>> rsp.data
bits("8b0000_1111")

Unions have a size, but no shape. They do NOT implement a __len__ method.

>>> Response.size
8

Union slicing behaves like a Vector:

>>> rsp[3:5]
bits("2b01")

Operators#

Bitwise#

seqlogic.not_(x: Bits | str) → Bits#

Unary bitwise logical NOT operator.

Perform logical negation on each bit of the input:

x

NOT(x)

0

1

1

0

X

X

-

-

For example:

>>> not_("4b-10X")
bits("4b-01X")

In expressions, you can use the unary ~ operator:

>>> a = bits("4b-10X")
>>> ~a
bits("4b-01X")
Parameters:

x – Bits or string literal.

Returns:

Bits of same type and equal size

Raises:

  • TypeError – x0 is not a valid Bits object.

  • ValueError – Error parsing string literal.

seqlogic.nor(x0: Bits | str, *xs: Bits | str) → Bits#

N-ary bitwise logical NOR operator.

Perform logical NOR on each bit of the inputs:

x0

x1

NOR(x0, x1)

Note

0

0

1

0

1

0

1

0

0

1

1

0

X

{0, 1, -}

X

X dominates all

1

-

0

1 dominates -

-

{0, -}

-

- dominates 0

For example:

>>> nor("16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b-0-X_000X_-01X_XXXX")

In expressions, you can use the unary ~ and binary | operators:

>>> a = bits("16b----_1111_0000_XXXX")
>>> b = bits("16b-10X_-10X_-10X_-10X")
>>> ~(a | b)
bits("16b-0-X_000X_-01X_XXXX")
Parameters:

  • x0 – Bits or string literal.

  • xs – Sequence of Bits equal size to x0.

Returns:

Bits equal size to x0.

Raises:

  • TypeError – x0 is not a valid Bits object, or xs[i] not equal size to x0.

  • ValueError – Error parsing string literal.

seqlogic.or_(x0: Bits | str, *xs: Bits | str) → Bits#

N-ary bitwise logical OR operator.

Perform logical OR on each bit of the inputs:

x0

x1

OR(x0, x1)

Note

0

0

0

0

1

1

1

0

1

1

1

1

X

{0, 1, -}

X

X dominates all

1

-

1

1 dominates -

-

{0, -}

-

- dominates 0

For example:

>>> or_("16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b-1-X_111X_-10X_XXXX")

In expressions, you can use the binary | operator:

>>> a = bits("16b----_1111_0000_XXXX")
>>> b = bits("16b-10X_-10X_-10X_-10X")
>>> a | b
bits("16b-1-X_111X_-10X_XXXX")
Parameters:

  • x0 – Bits or string literal.

  • xs – Sequence of Bits equal size to x0.

Returns:

Bits equal size to x0.

Raises:

  • TypeError – x0 is not a valid Bits object, or xs[i] not equal size to x0.

  • ValueError – Error parsing string literal.

seqlogic.nand(x0: Bits | str, *xs: Bits | str) → Bits#

N-ary bitwise logical NAND operator.

Perform logical NAND on each bit of the inputs:

x0

x1

NAND(x0, x1)

Note

0

0

1

0

1

1

1

0

1

1

1

0

X

{0, 1, -}

X

X dominates all

0

-

1

0 dominates -

-

{1, -}

-

- dominates 1

For example:

>>> nand("16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b--1X_-01X_111X_XXXX")

In expressions, you can use the unary ~ and binary & operators:

>>> a = bits("16b----_1111_0000_XXXX")
>>> b = bits("16b-10X_-10X_-10X_-10X")
>>> ~(a & b)
bits("16b--1X_-01X_111X_XXXX")
Parameters:

  • x0 – Bits or string literal.

  • xs – Sequence of Bits equal size to x0.

Returns:

Bits equal size to x0.

Raises:

  • TypeError – x0 is not a valid Bits object, or xs[i] not equal size to x0.

  • ValueError – Error parsing string literal.

seqlogic.and_(x0: Bits | str, *xs: Bits | str) → Bits#

N-ary bitwise logical AND operator.

Perform logical AND on each bit of the inputs:

x0

x1

AND(x0, x1)

Note

0

0

0

0

1

0

1

0

0

1

1

1

X

{0, 1, -}

X

X dominates all

0

-

0

0 dominates -

-

{1, -}

-

- dominates 1

For example:

>>> and_("16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b--0X_-10X_000X_XXXX")

In expressions, you can use the binary & operator:

>>> a = bits("16b----_1111_0000_XXXX")
>>> b = bits("16b-10X_-10X_-10X_-10X")
>>> a & b
bits("16b--0X_-10X_000X_XXXX")
Parameters:

  • x0 – Bits or string literal.

  • xs – Sequence of Bits equal size to x0.

Returns:

Bits equal size to x0.

Raises:

  • TypeError – x0 is not a valid Bits object, or xs[i] not equal size to x0.

  • ValueError – Error parsing string literal.

seqlogic.xnor(x0: Bits | str, *xs: Bits | str) → Bits#

N-ary bitwise logical XNOR operator.

Perform logical XNOR on each bit of the inputs:

x0

x1

XNOR(x0, x1)

Note

0

0

1

0

1

0

1

0

0

1

1

1

X

{0, 1, -}

X

X dominates all

-

{0, 1. -}

-

- dominates known

For example:

>>> xnor("16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b---X_-10X_-01X_XXXX")

In expressions, you can use the unary ~ and binary ^ operators:

>>> a = bits("16b----_1111_0000_XXXX")
>>> b = bits("16b-10X_-10X_-10X_-10X")
>>> ~(a ^ b)
bits("16b---X_-10X_-01X_XXXX")
Parameters:

  • x0 – Bits or string literal.

  • xs – Sequence of Bits equal size to x0.

Returns:

Bits equal size to x0.

Raises:

  • TypeError – x0 is not a valid Bits object, or xs[i] not equal size to x0.

  • ValueError – Error parsing string literal.

seqlogic.xor(x0: Bits | str, *xs: Bits | str) → Bits#

N-ary bitwise logical XOR operator.

Perform logical XOR on each bit of the inputs:

x0

x1

XOR(x0, x1)

Note

0

0

0

0

1

1

1

0

1

1

1

0

X

{0, 1, -}

X

X dominates all

-

{0, 1. -}

-

- dominates known

For example:

>>> xor("16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b---X_-01X_-10X_XXXX")

In expressions, you can use the binary ^ operator:

>>> a = bits("16b----_1111_0000_XXXX")
>>> b = bits("16b-10X_-10X_-10X_-10X")
>>> a ^ b
bits("16b---X_-01X_-10X_XXXX")
Parameters:

  • x0 – Bits or string literal.

  • xs – Sequence of Bits equal size to x0.

Returns:

Bits equal size to x0.

Raises:

  • TypeError – x0 is not a valid Bits object, or xs[i] not equal size to x0.

  • ValueError – Error parsing string literal.

seqlogic.mux(s: Bits | str, **xs: Bits | str) → Bits#

Bitwise logical multiplex (mux) operator.

Parameters:

  • s – Bits select.

  • xs – Bits or string literal, all equal size.

Mux input names are in the form xN, where N is a valid int. Muxes require at least one input. Any inputs not specified will default to “don’t care”.

For example:

>>> mux("2b00", x0="4b0001", x1="4b0010", x2="4b0100", x3="4b1000")
bits("4b0001")
>>> mux("2b10", x0="4b0001", x1="4b0010", x2="4b0100", x3="4b1000")
bits("4b0100")

Handles X and DC propagation:

>>> mux("2b1-", x0="4b0001", x1="4b0010", x2="4b0100", x3="4b1000")
bits("4b--00")
>>> mux("2b1X", x0="4b0001", x1="4b0010", x2="4b0100", x3="4b1000")
bits("4bXXXX")
Returns:

Bits equal size to xN inputs.

Raises:

  • TypeError – s or xN are not valid Bits objects, or xN mismatching size.

  • ValueError – Error parsing string literal.

seqlogic.ite(s: Bits | str, x1: Bits | str, x0: Bits | str) → Bits#

Ternary bitwise logical if-then-else (ITE) operator.

Perform logical ITE on each bit of the inputs:

s

x1

x0

ITE(s, x1, x0)

1

{0, 1, -}

x1

0

{0, 1, -}

x0

X

X

X

X

X

X

-

0

0

0

-

0

{1, -}

-

-

1

1

1

-

1

{0, -}

-

-

-

{0, 1, -}

-

For example:

>>> ite("1b0", "16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b-10X_-10X_-10X_XXXX")
>>> ite("1b1", "16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b---X_111X_000X_XXXX")
>>> ite("1b-", "16b----_1111_0000_XXXX", "16b-10X_-10X_-10X_-10X")
bits("16b---X_-1-X_--0X_XXXX")
Parameters:

  • s – Bits select

  • x1 – Bits or string literal.

  • x0 – Bits or string literal equal size to x1.

Returns:

Bits equal size to x1.

Raises:

  • TypeError – s or x1 are not valid Bits objects, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

Unary#

seqlogic.uor(x: Bits | str) → Scalar#

Unary OR reduction operator.

The identity of OR is 0. Compute an OR-sum over all the bits of x.

For example:

>>> uor("4b1000")
bits("1b1")

Empty input returns identity:

>>> uor(bits())
bits("1b0")
Parameters:

x – Bits or string literal.

Returns:

Scalar

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – Error parsing string literal.

seqlogic.uand(x: Bits | str) → Scalar#

Unary AND reduction operator.

The identity of AND is 1. Compute an AND-sum over all the bits of x.

For example:

>>> uand("4b0111")
bits("1b0")

Empty input returns identity:

>>> uand(bits())
bits("1b1")
Parameters:

x – Bits or string literal.

Returns:

Scalar

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – Error parsing string literal.

seqlogic.uxnor(x: Bits | str) → Scalar#

Unary XNOR reduction operator.

The identity of XOR is 0. Compute an XNOR-sum (even parity) over all the bits of x.

For example:

>>> uxnor("4b1010")
bits("1b1")

Empty input returns identity:

>>> uxnor(bits())
bits("1b1")
Parameters:

x – Bits or string literal.

Returns:

Scalar

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – Error parsing string literal.

seqlogic.uxor(x: Bits | str) → Scalar#

Unary XOR reduction operator.

The identity of XOR is 0. Compute an XOR-sum (odd parity) over all the bits of x.

For example:

>>> uxor("4b1010")
bits("1b0")

Empty input returns identity:

>>> uxor(bits())
bits("1b0")
Parameters:

x – Bits or string literal.

Returns:

Scalar

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – Error parsing string literal.

Arithmetic#

seqlogic.decode(x: Bits | str) → Vector#

Decode dense encoding to sparse, one-hot encoding.

For example:

>>> decode("2b00")
bits("4b0001")
>>> decode("2b01")
bits("4b0010")
>>> decode("2b10")
bits("4b0100")
>>> decode("2b11")
bits("4b1000")

Empty input returns 1b1:

>>> decode(bits())
bits("1b1")
Parameters:

x – Bits or string literal.

Returns:

One hot Scalar or Vector w/ size = 2**x.size

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – Error parsing string literal.

seqlogic.encode_onehot(x: Bits | str) → Vector#

Compress one-hot encoding to an index.

The index is the highest bit set in the input.

For example:

>>> encode_onehot("2b01")
bits("1b0")
>>> encode_onehot("2b10")
bits("1b1")
>>> encode_onehot("3b010")
bits("2b01")
Parameters:

x – Bits or string literal.

Returns:

Vector w/ size = clog2(x.size)

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – x is not one-hot encoded.

seqlogic.encode_priority(x: Bits | str) → tuple[Vector, Scalar]#

Compress priority encoding to (index, valid) tuple.

The index is the highest bit set in the input.

For example:

>>> encode_priority("2b01")
(bits("1b0"), bits("1b1"))
>>> encode_priority("2b10")
(bits("1b1"), bits("1b1"))
>>> encode_priority("3b1--")
(bits("2b10"), bits("1b1"))
Parameters:

x – Bits or string literal.

Returns:

Vector w/ size = clog2(x.size) Scalar valid bit

Return type:

Tuple of Vector and Scalar

Raises:

TypeError – x is not a valid Bits object.

seqlogic.add(a: Bits | str, b: Bits | str, ci: Scalar | str | None = None) → Bits#

Addition with carry-in, but NO carry-out.

For example:

>>> add("4d2", "4d2")
bits("4b0100")

>>> add("2d2", "2d2")
bits("2b00")
Parameters:

  • a – Bits or string literal

  • b – Bits or string literal

  • ci – Scalar carry-in, or None. None defaults to carry-in 0.

Returns:

Bits sum w/ size equal to max(a.size, b.size).

Raises:

  • TypeError – a, b, or ci are not valid Bits objects.

  • ValueError – Error parsing string literal.

seqlogic.adc(a: Bits | str, b: Bits | str, ci: Scalar | str | None = None) → Vector#

Addition with carry-in, and carry-out.

For example:

>>> adc("4d2", "4d2")
bits("5b0_0100")

>>> adc("2d2", "2d2")
bits("3b100")
Parameters:

  • a – Bits or string literal

  • b – Bits or string literal

  • ci – Scalar carry-in, or None. None defaults to carry-in 0.

Returns:

Vector sum w/ size equal to max(a.size, b.size) + 1. The most significant bit is the carry-out.

Raises:

  • TypeError – a, b, or ci are not valid Bits objects.

  • ValueError – Error parsing string literal.

seqlogic.sub(a: Bits | str, b: Bits | str) → Bits#

Twos complement subtraction, with NO carry-out.

Parameters:

  • a – Bits or string literal

  • b – Bits or string literal equal size to a.

Returns:

Bits sum equal size to a and b.

Raises:

  • TypeError – a, or b are not valid Bits objects, or a not equal size to b.

  • ValueError – Error parsing string literal.

seqlogic.sbc(a: Bits | str, b: Bits | str) → Vector#

Twos complement subtraction, with carry-out.

Parameters:

  • a – Bits or string literal

  • b – Bits or string literal equal size to a.

Returns:

Bits sum w/ size one larger than a and b. The most significant bit is the carry-out.

Raises:

  • TypeError – a, or b are not valid Bits objects, or a not equal size to b.

  • ValueError – Error parsing string literal.

seqlogic.neg(x: Bits | str) → Bits#

Twos complement negation, with NO carry-out.

Parameters:

x – Bits or string literal

Returns:

Bits equal size to x.

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – Error parsing string literal.

seqlogic.ngc(x: Bits | str) → Vector#

Twos complement negation, with carry-out.

Parameters:

x – Bits or string literal

Returns:

Bits w/ size one larger than x. The most significant bit is the carry-out.

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – Error parsing string literal.

seqlogic.mul(a: Bits | str, b: Bits | str) → Vector#

Unsigned multiply.

For example:

>>> mul("4d2", "4d2")
bits("8b0000_0100")

>>> add("2d2", "2d2")
bits("2b00")
Parameters:

  • a – Bits or string literal

  • b – Bits or string literal

Returns:

Vector product w/ size a.size + b.size

Raises:

  • TypeError – a or b are not valid Bits objects.

  • ValueError – Error parsing string literal.

seqlogic.div(a: Bits | str, b: Bits | str) → Bits#

Unsigned divide.

Parameters:

  • a – Bits or string literal

  • b – Bits or string literal

Returns:

Vector quotient w/ size a.size

Raises:

  • TypeError – a or b are not valid Bits objects.

  • ValueError – Error parsing string literal.

seqlogic.mod(a: Bits | str, b: Bits | str) → Bits#

Unsigned modulo.

Parameters:

  • a – Bits or string literal

  • b – Bits or string literal

Returns:

Vector remainder w/ size b.size

Raises:

  • TypeError – a or b are not valid Bits objects.

  • ValueError – Error parsing string literal.

seqlogic.lsh(x: Bits | str, n: Bits | str | int) → Bits#

Logical left shift by n bits.

Fill bits with zeros.

For example:

>>> lsh("4b1011", 2)
bits("4b1100")
Parameters:

  • x – Bits or string literal.

  • n – Bits, string literal, or int Non-negative bit shift count.

Returns:

Bits left-shifted by n bits.

Raises:

  • TypeError – x is not a valid Bits object, or n is not a valid bit shift count.

  • ValueError – Error parsing string literal, or negative shift amount.

seqlogic.rsh(x: Bits | str, n: Bits | str | int) → Bits#

Logical right shift by n bits.

Fill bits with zeros.

For example:

>>> rsh("4b1101", 2)
bits("4b0011")
Parameters:

  • x – Bits or string literal.

  • n – Bits, string literal, or int Non-negative bit shift count.

Returns:

Bits right-shifted by n bits.

Raises:

  • TypeError – x is not a valid Bits object, or n is not a valid bit shift count.

  • ValueError – Error parsing string literal, or negative shift amount.

seqlogic.srsh(x: Bits | str, n: Bits | str | int) → Bits#

Arithmetic (signed) right shift by n bits.

Fill bits with most significant bit (sign).

For example:

>>> srsh("4b1101", 2)
bits("4b1111")
Parameters:

  • x – Bits or string literal.

  • n – Bits, string literal, or int Non-negative bit shift count.

Returns:

Bits right-shifted by n bits.

Raises:

  • TypeError – x is not a valid Bits object, or n is not a valid bit shift count.

  • ValueError – Error parsing string literal, or negative shift amount.

Word#

seqlogic.xt(x: Bits | str, n: int) → Bits#

Unsigned extend by n bits.

Fill high order bits with zero.

For example:

>>> xt("2b11", 2)
bits("4b0011")
Parameters:

  • x – Bits or string literal.

  • n – Non-negative number of bits.

Returns:

Bits zero-extended by n bits.

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – If n is negative.

seqlogic.sxt(x: Bits | str, n: int) → Bits#

Sign extend by n bits.

Fill high order bits with sign.

For example:

>>> sxt("2b11", 2)
bits("4b1111")
Parameters:

  • x – Bits or string literal.

  • n – Non-negative number of bits.

Returns:

Bits sign-extended by n bits.

Raises:

  • TypeError – x is not a valid Bits object.

  • ValueError – If n is negative.

seqlogic.lrot(x: Bits | str, n: Bits | str | int) → Bits#

Rotate left by n bits.

For example:

>>> lrot("4b1011", 2)
bits("4b1110")
Parameters:

  • x – Bits or string literal.

  • n – Bits, string literal, or int Non-negative bit rotate count.

Returns:

Bits left-rotated by n bits.

Raises:

  • TypeError – x is not a valid Bits object, or n is not a valid bit rotate count.

  • ValueError – Error parsing string literal, or negative rotate amount.

seqlogic.rrot(x: Bits | str, n: Bits | str | int) → Bits#

Rotate right by n bits.

For example:

>>> rrot("4b1101", 2)
bits("4b0111")
Parameters:

  • x – Bits or string literal.

  • n – Bits, string literal, or int Non-negative bit rotate count.

Returns:

Bits right-rotated by n bits.

Raises:

  • TypeError – x is not a valid Bits object, or n is not a valid bit rotate count.

  • ValueError – Error parsing string literal, or negative rotate amount.

seqlogic.cat(*objs: Bits | int | str) → Vector#

Concatenate a sequence of Vectors.

Parameters:

objs – a sequence of vec/bool/lit objects.

Returns:

A Vec instance.

Raises:

TypeError – If input obj is invalid.

seqlogic.rep(obj: Bits | int | str, n: int) → Vector#

Repeat a Vector n times.

seqlogic.pack(x: Bits | str, n: int = 1) → Bits#

Pack n-bit blocks in right to left order.

Predicate#

seqlogic.match(x0: Bits | str, x1: Bits | str) → Scalar#

Pattern match operator.

Similar to eq operator, but with support for - wildcards.

For example:

>>> match("2b01", "2b0-")
bits("1b1")
>>> match("2b--", "2b10")
bits("1b1")
>>> match("2b01", "2b10")
bits("1b0")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.eq(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Equal (==) reduction operator.

Equivalent to uand(xnor(x0, x1)).

For example:

>>> eq("2b01", "2b00")
bits("1b0")
>>> eq("2b01", "2b01")
bits("1b1")
>>> eq("2b01", "2b10")
bits("1b0")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.ne(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical NotEqual (!=) reduction operator.

Equivalent to uor(xor(x0, x1)).

For example:

>>> ne("2b01", "2b00")
bits("1b1")
>>> ne("2b01", "2b01")
bits("1b0")
>>> ne("2b01", "2b10")
bits("1b1")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.lt(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Unsigned LessThan (<) reduction operator.

Returns Scalar result of x0.to_uint() < x1.to_uint(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> lt("2b01", "2b00")
bits("1b0")
>>> lt("2b01", "2b01")
bits("1b0")
>>> lt("2b01", "2b10")
bits("1b1")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.le(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Unsigned LessThanOrEqual (≤) reduction operator.

Returns Scalar result of x0.to_uint() <= x1.to_uint(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> le("2b01", "2b00")
bits("1b0")
>>> le("2b01", "2b01")
bits("1b1")
>>> le("2b01", "2b10")
bits("1b1")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.gt(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Unsigned GreaterThan (>) reduction operator.

Returns Scalar result of x0.to_uint() > x1.to_uint(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> gt("2b01", "2b00")
bits("1b1")
>>> gt("2b01", "2b01")
bits("1b0")
>>> gt("2b01", "2b10")
bits("1b0")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.ge(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Unsigned GreaterThanOrEqual (≥) reduction operator.

Returns Scalar result of x0.to_uint() >= x1.to_uint(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> ge("2b01", "2b00")
bits("1b1")
>>> ge("2b01", "2b01")
bits("1b1")
>>> ge("2b01", "2b10")
bits("1b0")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.slt(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Signed LessThan (<) reduction operator.

Returns Scalar result of x0.to_int() < x1.to_int(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> slt("2b00", "2b11")
bits("1b0")
>>> slt("2b00", "2b00")
bits("1b0")
>>> slt("2b00", "2b01")
bits("1b1")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.sle(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Signed LessThanOrEqual (≤) reduction operator.

Returns Scalar result of x0.to_int() <= x1.to_int(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> sle("2b00", "2b11")
bits("1b0")
>>> sle("2b00", "2b00")
bits("1b1")
>>> sle("2b00", "2b01")
bits("1b1")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.sgt(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Signed GreaterThan (>) reduction operator.

Returns Scalar result of x0.to_int() > x1.to_int(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> sgt("2b00", "2b11")
bits("1b1")
>>> sgt("2b00", "2b00")
bits("1b0")
>>> sgt("2b00", "2b01")
bits("1b0")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

seqlogic.sge(x0: Bits | str, x1: Bits | str) → Scalar#

Binary logical Signed GreaterThanOrEqual (≥) reduction operator.

Returns Scalar result of x0.to_int() >= x1.to_int(). For performance reasons, use simple X/- propagation: X dominates {-, known}, and - dominates known.

For example:

>>> sge("2b00", "2b11")
bits("1b1")
>>> sge("2b00", "2b00")
bits("1b1")
>>> sge("2b00", "2b01")
bits("1b0")
Parameters:

  • x0 – Bits or string literal.

  • x1 – Bits or string literal equal size to x0.

Returns:

Scalar

Raises:

  • TypeError – x0 or x1 is not a valid Bits object, or x0 not equal size to x1.

  • ValueError – Error parsing string literal.

Factory Functions#

seqlogic.bits(obj=None) → Array#

Create a shaped Bits object using standard input formats.

For example, empty input returns an Empty instance.

>>> bits()
bits([])
>>> bits(None)
bits([])

bool, int, and string literal inputs:

>>> bits(False)
bits("1b0")
>>> bits([False, True, False, True])
bits("4b1010")
>>> bits("8d42")
bits("8b0010_1010")

Use a list of inputs to create arbitrary shaped inputs:

>>> x = bits([["2b00", "2b01"], ["2b10", "2b11"]])
>>> x
bits([["2b00", "2b01"],
      ["2b10", "2b11"]])
>>> x.shape
(2, 2, 2)
Parameters:

obj – Object that can be converted to a Bits instance.

Returns:

Shaped Bits instance.

Raises:

TypeError – If input obj is invalid.

seqlogic.stack(*objs: Array | int | str) → Array#

Stack a sequence of Bits w/ same shape into a higher dimensional shape.

For a sequence length N with shape M, the output shape will be M x N.

For example, a sequence of scalars stacked to a vector:

>>> stack(0, 1, 0, 1)
bits("4b1010")

Or a sequence of vectors stacked to an array:

>>> x0 = stack("2b00", "2b01")
>>> x1 = stack("2b10", "2b11")
>>> y = stack(x0, x1)
>>> y
bits([["2b00", "2b01"],
      ["2b10", "2b11"]])
>>> y.shape
(2, 2, 2)
Parameters:

objs – a sequence of vec/bits/bool/lit objects.

Returns:

Shaped Bits instance.

Raises:

TypeError – If input obj is invalid.

seqlogic.u2bv(n: int, size: int | None = None) → Vector#

Convert nonnegative int to Vector.

For example:

>>> u2bv(42, size=8)
bits("8b0010_1010")
Parameters:

  • n – Nonnegative int to convert.

  • size – Optional int output size. Defaults to minimum required size.

Returns:

Vector

Raises:

ValueError – n is negative or overflows the output size.

seqlogic.i2bv(n: int, size: int | None = None) → Vector#

Convert int to Vector.

For example:

>>> i2bv(42, size=8)
bits("8b0010_1010")
>>> i2bv(-42, size=8)
bits("8b1101_0110")
Parameters:

  • n – int to convert.

  • size – Optional int output size. Defaults to minimum required size.

Returns:

Vector

Raises:

ValueError – n overflows the output size.