Quick Start

This chapter will get you started using bvwx.

Install

To install the latest release of BVWX, run:

$ pip install bvwx

See the Installation chapter for more details.

Basic Boolean Algebra

Fire up a Python REPL, ignore the advice given in PEP8’s Imports section, and wildcard-import all names from bvwx:

>>> from bvwx import *

Create two 4x4 bit arrays x0 and x1, with various known (0, 1), and unknown (-, X) bit values:

>>> x0 = bits(["4b----", "4b1111", "4b0000", "4bXXXX"])
>>> x1 = bits(["4b-10X", "4b-10X", "4b-10X", "4b-10X"])
>>> type(x0)
bvwx._bits.Array[4,4]
>>> x0.size
16
>>> x0.shape
(4, 4)

Invoke the Boolean Algebra bitwise operators NOT (~), OR (|), AND (&), and XOR (^) with x1 and x2 as arguments:

>>> ~x0
bits(["4b----", "4b0000", "4b1111", "4bXXXX"])
>>> ~x1
bits(["4b-01X", "4b-01X", "4b-01X", "4b-01X"])
>>> x0 | x1
bits(["4b-1-X", "4b111X", "4b-10X", "4bXXXX"])
>>> x0 & x1
bits(["4b--0X", "4b-10X", "4b000X", "4bXXXX"])
>>> x0 ^ x1
bits(["4b---X", "4b-01X", "4b-10X", "4bXXXX"])

The multi-dimensional Array is the most powerful “shaped” data type. We can perform similar operations on one-dimensional Vector, zero-dimensional Scalar, and even Empty bit sequences:

>>> type(bits("4b0000"))
bvwx._bits.Vector[4]
>>> type(bits("1b1"))
bvwx._bits.Scalar
>>> type(bits())
bvwx._bits.Empty

User-Defined Types

Now that we have experimented with pre-defined data types, let’s create some new ones. Define a C-style Enum:

>>> class Color(Enum):
...     RED   = "2b00"
...     GREEN = "2b01"
...     BLUE  = "2b10"
...
>>> type(Color)
bvwx._enum._EnumMeta
>>> Color.size
2

Despite the fancy type definition, enums are just vectors. Use the Color values in expressions:

# Defined values work as expected
>>> Color.GREEN & Color.BLUE
Color.RED

# Undefined values are tolerated
>>> Color.GREEN | Color.BLUE
Color("2b11")

Now define a C-style Struct:

>>> class Pixel(Struct):
...     r: Vec[8]
...     g: Vec[8]
...     b: Vec[8]
...
>>> type(Pixel)
bvwx._struct._StructMeta
>>> Pixel.size
24

Create Pixel instances, and use them in expressions:

>>> maize = Pixel(r="8hFF", g="8hCB", b="8h05")
>>> blue = Pixel(r="8h00", g="8h27", b="8h4C")

>>> maize & blue
Pixel(
    r=bits("8b0000_0000"),
    g=bits("8b0000_0011"),
    b=bits("8b0000_0100"),
)
>>> maize | blue
Pixel(
    r=bits("8b1111_1111"),
    g=bits("8b1110_1111"),
    b=bits("8b0100_1101"),
)

Finally, create a C-style Union from Color and Pixel types:

>>> class MyUnion(Union):
...     c: Color
...     p: Pixel
...
>>> type(MyUnion)
bvwx._union._UnionMeta
>>> MyUnion.size
24

Create MyUnion instances, and use them in expressions:

>>> u1 = MyUnion(Color.RED)
>>> u2 = MyUnion(maize)
>>> u1 | u2
MyUnion(
    c=Color("2b11"),
    p=Pixel(
        r=bits("8bXXXX_XX11"),
        g=bits("8bXXXX_XXXX"),
        b=bits("8bXXXX_XXXX"),
    ),
)

Next Steps

Note

To self: Write documentation about other stuff, then point users to it.