Multi-Valued Logic - kyupy.logic

Core module for handling 2-, 4-, and 8-valued logic data and signal values.

Logic values are stored in numpy arrays with data type np.uint8. There are no explicit data structures in KyuPy for holding patterns, pattern sets or vectors. However, there are conventions on logic value encoding and on the order of axes. Utility functions defined here follow these conventions.

8 logic values are defined as integer constants.

  • For 2-valued logic: ZERO and ONE

  • 4-valued logic adds: UNASSIGNED and UNKNOWN

  • 8-valued logic adds: RISE, FALL, PPULSE, and NPULSE.

In general, the bits in these constants have the following meaning:

  • bit0: Final/settled binary value of a signal

  • bit1: Initial binary value of a signal

  • bit2: Activity or transitions are present on a signal

Except when bit0 differs from bit1, but bit2 (activity) is 0:

  • bit0 = 1, bit1 = 0, bit2 = 0 means UNKNOWN in 4-valued and 8-valued logic.

  • bit0 = 0, bit1 = 1, bit2 = 0 means UNASSIGNED in 4-valued and 8-valued logic.

2-valued logic only considers bit0, but should store logic one as ONE=0b011 for interoperability. 4-valued logic only considers bit0 and bit1. 8-valued logic considers all 3 bits.

Logic values are stored in numpy arrays of data type np.uint8. The axis convention is as follows:

  • The last axis goes along patterns/vectors. I.e. values[...,0] is pattern 0, values[...,1] is pattern 1, etc.

  • The second-to-last axis goes along the I/O and flip-flops of circuits. For a circuit c, this axis is usually len(c.s_nodes) long. The values of all inputs, outputs and flip-flops are stored within the same array and the location along the second-to-last axis is determined by the order in s_nodes.

Two storage formats are used in KyuPy:

  • mv... (for “multi-valued”): Each logic value is stored in the least significant 3 bits of np.uint8.

  • bp... (for “bit-parallel”): Groups of 8 logic values are stored as three np.uint8. This format is used for bit-parallel logic simulations. It is also more memory-efficient.

The functions in this module use the mv... and bp... prefixes to signify the storage format they operate on.

kyupy.logic.ZERO = 0

Integer constant 0b000 for logic-0. '0', 0, False, 'L', and 'l' are interpreted as ZERO.

kyupy.logic.UNKNOWN = 1

Integer constant 0b001 for unknown or conflict. 'X', or any other value is interpreted as UNKNOWN.

kyupy.logic.UNASSIGNED = 2

Integer constant 0b010 for unassigned or high-impedance. '-', None, 'Z', and 'z' are interpreted as UNASSIGNED.

kyupy.logic.ONE = 3

Integer constant 0b011 for logic-1. '1', 1, True, 'H', and 'h' are interpreted as ONE.

kyupy.logic.PPULSE = 4

Integer constant 0b100 for positive pulse, meaning initial and final values are 0, but there is some activity on a signal. 'P', 'p', and '^' are interpreted as PPULSE.

kyupy.logic.RISE = 5

Integer constant 0b110 for a rising transition. 'R', 'r', and '/' are interpreted as RISE.

kyupy.logic.FALL = 6

Integer constant 0b101 for a falling transition. 'F', 'f', and '\' are interpreted as FALL.

kyupy.logic.NPULSE = 7

Integer constant 0b111 for negative pulse, meaning initial and final values are 1, but there is some activity on a signal. 'N', 'n', and 'v' are interpreted as NPULSE.

kyupy.logic.interpret(value)

Converts characters, strings, and lists of them to lists of logic constants defined above.

Parameters:

value – A character (string of length 1), Boolean, Integer, None, or Iterable. Iterables (such as strings) are traversed and their individual characters are interpreted.

Returns:

A logic constant or a (possibly multi-dimensional) list of logic constants.

kyupy.logic.mvarray(*a)

Converts (lists of) Boolean values or strings into a multi-valued array.

The given values are interpreted and the axes are arranged as per KyuPy’s convention. Use this function to convert strings into multi-valued arrays.

kyupy.logic.mv_str(mva, delim='\n')

Renders a given multi-valued array into a string.

kyupy.logic.mv_not(x1: ndarray, out=None)

A multi-valued NOT operator.

Parameters:

  • x1 – A multi-valued array.

  • out – An optional storage destination. If None, a new multi-valued array is returned.

Returns:

A multi-valued array with the result.

kyupy.logic.mv_or(x1, x2, out=None)

A multi-valued OR operator.

Parameters:

  • x1 – A multi-valued array.

  • x2 – A multi-valued array.

  • out – An optional storage destination. If None, a new multi-valued array is returned.

Returns:

A multi-valued array with the result.

kyupy.logic.mv_and(x1, x2, out=None)

A multi-valued AND operator.

Parameters:

  • x1 – A multi-valued array.

  • x2 – A multi-valued array.

  • out – An optional storage destination. If None, a new multi-valued array is returned.

Returns:

A multi-valued array with the result.

kyupy.logic.mv_xor(x1, x2, out=None)

A multi-valued XOR operator.

Parameters:

  • x1 – A multi-valued array.

  • x2 – A multi-valued array.

  • out – An optional storage destination. If None, a new multi-valued array is returned.

Returns:

A multi-valued array with the result.

kyupy.logic.mv_latch(d, t, q_prev, out=None)

A multi-valued latch operator.

A latch outputs d when transparent (t is high). It outputs q_prev when in latched state (t is low).

Parameters:

  • d – A multi-valued array for the data input.

  • t – A multi-valued array for the control input.

  • q_prev – A multi-valued array with the output value of this latch from the previous clock cycle.

  • out – An optional storage destination. If None, a new multi-valued array is returned.

Returns:

A multi-valued array for the latch output q.

kyupy.logic.mv_transition(init, final, out=None)

Computes the logic transitions from the initial values of init to the final values of final. Pulses in the input data are ignored. If any of the inputs are UNKNOWN, the result is UNKNOWN. If init is UNASSIGNED, the result is the final value of final. If final is UNASSIGNED, the result is the initial value of init. If both inputs are UNASSIGNED, the result is UNASSIGNED.

Parameters:

  • init – A multi-valued array.

  • final – A multi-valued array.

  • out – An optional storage destination. If None, a new multi-valued array is returned.

Returns:

A multi-valued array with the result.

kyupy.logic.mv_to_bp(mva)

Converts a multi-valued array into a bit-parallel array.

kyupy.logic.mv_init(mva)

Returns the initial binary values for mva.

kyupy.logic.mv_final(mva)

Returns the final binary value of mva.

kyupy.logic.bparray(*a)

Converts (lists of) Boolean values or strings into a bit-parallel array.

The given values are interpreted and the axes are arranged as per KyuPy’s convention. Use this function to convert strings into bit-parallel arrays.

kyupy.logic.bp_to_mv(bpa)

Converts a bit-parallel array into a multi-valued array.

kyupy.logic.unpackbits(a: ndarray)

Unpacks the bits of given ndarray a.

Similar to np.unpackbits, but accepts any dtype, preserves the shape of a and adds a new last axis with the bits of each item. Bits are in ‘little’-order, i.e., a[…,0] is the least significant bit of each item.

kyupy.logic.packbits(a, dtype: type[~typing.Any] | ~numpy.dtype[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | tuple[~typing.Any, ~typing.Any] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | str | None = <class 'numpy.uint8'>)

Packs the values of a boolean-valued array a along its last axis into bits.

Similar to np.packbits, but returns an array of given dtype and the shape of a with the last axis removed. The last axis of a is truncated or padded according to the bit-width of the given dtype. Signed integer datatypes are padded with the most significant bit, all others are padded with 0.