csdigit package

Submodules

csdigit.cli module

This is a to_csd file that can serve as a starting point for a Python console script. To run this script uncomment the following lines in the [options.entry_points] section in setup.cfg:

console_scripts =
     to_csd = csdigit.to_csd:run

Then run pip install . (or pip install -e . for editable mode) which will install the command to_csd inside your current environment.

Besides console scripts, the header (i.e. until _logger…) of this file can also be used as template for Python modules.

References

csdigit.cli.main(args: List[str]) → None[source]

Wrapper allowing main() to be called with string arguments in a CLI fashion

Instead of returning the value from main(), it prints the result to the stdout in a nicely formatted message.

Parameters:

args (List[str]) – command line parameters as list of strings (for example ["--verbose", "42"]).

csdigit.cli.parse_args(args: List[str]) → Namespace[source]

Parse command line parameters

Parameters:

args (List[str]) – command line parameters as list of strings (for example ["--help"]).

Returns:

command line parameters namespace

Return type:

argparse.Namespace

csdigit.cli.run() → None[source]

Calls main() passing the CLI arguments extracted from sys.argv

This function can be used as entry point to create console scripts with setuptools.

csdigit.cli.setup_logging(loglevel: int) → None[source]

Setup basic logging

Parameters:

loglevel (int) – minimum loglevel for emitting messages

csdigit.csd module

Canonical Signed Digit (CSD) Conversion

This code is all about converting numbers between decimal format and a special representation called Canonical Signed Digit (CSD). CSD is a way of writing numbers using only three symbols: 0, +, and -. It’s particularly useful in certain areas of computer science and digital signal processing.

The main purpose of this code is to provide functions that can convert decimal numbers to CSD format and vice versa. It takes in regular decimal numbers (like 28.5 or -0.5) and converts them to CSD strings (like “+00-00.+” or “0.-“), and it can also do the reverse, taking CSD strings and converting them back to decimal numbers.

The code contains several functions, each with a specific role:

  1. to_csd: This function takes a decimal number and the number of decimal places desired, and outputs a CSD string. For example, it can convert 28.5 to “+00-00.+0” (with 2 decimal places).

  2. to_csd_i: Similar to to_csd, but it works specifically with integers. It converts whole numbers to CSD format without a decimal point.

  3. to_decimal_using_pow and to_decimal: These functions do the opposite of to_csd. They take a CSD string and convert it back to a decimal number.

  4. to_csdnnz: This function is a variation of to_csd that allows you to specify the maximum number of non-zero digits in the result.

  1. to_csdnnz_i: This function is a variation of to_csd_i that allows you to specify the maximum number of non-zero digits in the result.

The code achieves its purpose through a series of mathematical operations and logical checks. For the decimal to CSD conversion, it uses powers of 2 to determine which symbols (+, -, or 0) to use at each position in the CSD string. It repeatedly divides the input number by 2 and checks if it’s greater than, less than, or close to certain thresholds to decide which symbol to use.

For the CSD to decimal conversion, it goes through each symbol in the CSD string, multiplying the running total by 2 and adding 1, subtracting 1, or doing nothing based on whether the symbol is +, -, or 0.

An important aspect of the code is how it handles the decimal point in CSD representations. It uses a separate logic for the part before the decimal point (the integral part) and the part after (the fractional part).

The code also includes error checking to ensure that only valid CSD symbols are used, and it provides detailed documentation and examples for each function to help users understand how to use them.

Overall, this code provides a comprehensive set of tools for working with CSD representations, allowing users to easily convert between decimal and CSD formats in various ways.

csdigit.csd.to_csd(decimal_value: float, places: int) → str[source]

The to_csd function converts a given decimal number to its Canonical Signed Digit (CSD) representation with a specified number of decimal places.

Original author: Harnesser <https://sourceforge.net/projects/pycsd/> License: GPL2

Parameters:

  • decimal_value (float) – The decimal_value parameter is a double precision floating-point number that represents the value to be converted to CSD (Canonical Signed Digit) representation

  • places (int) – The places parameter in the to_csd function represents the number of decimal places to include in the CSD (Canonical Signed Digit) representation of the given decimal_value

Returns:

The function to_csd returns a string representation of the given decimal_value in Canonical Signed Digit (CSD) format.

Examples

>>> to_csd(28.5, 2)
'+00-00.+0'
>>> to_csd(-0.5, 2)
'0.-0'
>>> to_csd(0.0, 2)
'0.00'
>>> to_csd(0.0, 0)
'0.'
csdigit.csd.to_csd_i(decimal_value: int) → str[source]

The to_csd_i function converts a given integer into a Canonical Signed Digit (CSD) representation.

Original author: Harnesser <https://sourceforge.net/projects/pycsd/> License: GPL2

Parameters:

decimal_value (int) – The decimal_value parameter is an integer that represents the decimal value to be converted to CSD format

Returns:

The function to_csd_i returns a string containing the CSD (Canonical Signed Digit) value.

Examples

>>> to_csd_i(28)
'+00-00'
>>> to_csd_i(-0)
'0'
>>> to_csd_i(0)
'0'
csdigit.csd.to_csdnnz(decimal_value: float, nnz: int) → str[source]

The to_csdnnz function converts a given decimal number into a Canonical Signed Digit (CSD) representation with a specified number of non-zero digits.

Original author: Harnesser <https://sourceforge.net/projects/pycsd/> License: GPL2

Parameters:

  • decimal_value (float) – The decimal_value parameter is a double precision floating-point number that represents the input value for conversion to CSD (Canonic Signed Digit) fixed-point representation

  • nnz (int) – The parameter nnz stands for “number of non-zero bits”. It represents the maximum number of non-zero bits allowed in the output CSD (Canonical Signed Digit) representation of the given decimal_value

Returns:

The function to_csdnnz returns a string representation of the given decimal_value in Canonical Signed Digit (CSD) format.

Examples

>>> to_csdnnz(28.5, 4)
'+00-00.+'
>>> to_csdnnz(-0.5, 4)
'0.-'
>>> to_csdnnz(0.0, 4)
'0'
>>> to_csdnnz(0.5, 4)
'0.+'
csdigit.csd.to_csdnnz_i(decimal_value: int, nnz: int) → str[source]

The to_csdnnz_i function converts a given integer into a Canonical Signed Digit (CSD) representation with a specified number of non-zero digits.

Original author: Harnesser <https://sourceforge.net/projects/pycsd/> License: GPL2

Parameters:

  • decimal_value (int) – The decimal_value parameter is an integer that represents the decimal value to be converted to CSD format

  • nnz (int) – The parameter nnz stands for “number of non-zero bits”. It represents the maximum number of non-zero bits allowed in the output CSD (Canonical Signed Digit) representation of the given decimal_value

Returns:

The function to_csdnnz_i returns a string representation of the given decimal_value in Canonical Signed Digit (CSD) format.

Examples

>>> to_csdnnz_i(28, 4)
'+00-00'
>>> to_csdnnz_i(-0, 4)
'0'
>>> to_csdnnz_i(0, 4)
'0'
>>> to_csdnnz_i(37, 2)
'+00+00'
>>> to_csdnnz_i(158, 2)
'+0+00000'
csdigit.csd.to_decimal(csd: str) → float[source]

Convert CSD string to decimal number.

Original author: Harnesser <https://sourceforge.net/projects/pycsd/> License: GPL2

Parameters:

csd (str) – The csd parameter is a string containing the CSD (Canonical Signed Digit) value that we want to convert to a decimal number

Examples

>>> to_decimal("+00-00.+")
28.5
>>> to_decimal("0.-")
-0.5
>>> to_decimal("0")
0
>>> to_decimal("0.0")
0.0
>>> to_decimal("0.+")
0.5
csdigit.csd.to_decimal_using_pow(csd: str) → float[source]

The to_decimal_using_pow function converts a Canonical Signed Digit (CSD) string to a decimal number using the pow function.

Deprecated since version 0.1.0: Use to_decimal instead.

Original author: Harnesser <https://sourceforge.net/projects/pycsd/> License: GPL2

Parameters:

csd (str) – The csd parameter is a string containing the CSD (Canonical Signed Digit) value

Examples

>>> to_decimal_using_pow("+00-00.+")
28.5
>>> to_decimal_using_pow("0.-")
-0.5
>>> to_decimal_using_pow("0")
0.0
>>> to_decimal_using_pow("0.0")
0.0
>>> to_decimal_using_pow("0.+")
0.5

csdigit.csd_multiplier module

CSD Multiplier — Verilog Code Generation

Translates a Canonical Signed Digit (CSD) string into a synthesizable Verilog module that implements constant multiplication using only shift-and-add/subtract operations. When the CSD string contains repeated patterns, LCSRe (Longest Common Substring with Repeated Elements) is used to share hardware via a sub-expression wire.

csdigit.csd_multiplier.generate_csd_multiplier(csd: str, input_width: int, max_power: int) → str[source]

Generate Verilog code for a CSD multiplier module with LCSRe optimization.

When the CSD string contains repeated non-overlapping patterns (detected via the longest_repeated_substring algorithm), the generated Verilog factors out a shared sub-expression wire — reducing the number of adders.

Parameters:

  • csd – CSD string (e.g., “+00-00+0+”)

  • input_width – Bit width of the input signal x

  • max_power – Highest power of two in the CSD (must be len(csd)-1)

Returns:

Verilog module code as a string

Raises:

ValueError – If csd length doesn’t match max_power+1 or the string contains characters other than ‘+’, ‘-’, ‘0’

csdigit.csd_multiplier.generate_csd_multipliers(coeffs: list[tuple[str, str, int, int]], module_name: str = 'csd_filter') → str[source]

Generate a Verilog module with multiple CSD multipliers and cross-CSE.

When the same CSD substring appears in multiple coefficients, a shared sub-expression wire is created — reducing total adder count across the entire filter.

All coefficients must share the same input_width and max_power so that the same bit position encodes the same power of two across all multipliers. If a coefficient is narrower, pad its CSD with leading '0' characters.

Parameters:

  • coeffs – List of (output_name, csd_str, input_width, max_power) tuples. All entries must share the same input_width and max_power.

  • module_name – Name for the generated Verilog module.

Returns:

Verilog module code as a string

csdigit.lcsre module

Longest Repeated Substring Finder

This code defines a function called longest_repeated_substring that finds the longest repeated non-overlapping substring within a given string. The purpose of this code is to identify and return the longest sequence of characters that appears more than once in the input string, without the repetitions overlapping each other.

The function takes a single input: a string called cs, which represents the text in which we want to

find the repeated substring. The output of the function is another string, which is the longest repeated

non-overlapping substring found in the input.

To achieve its purpose, the code uses a dynamic programming approach. It creates a 2D table (called LCSRe) to keep track of the lengths of repeated substrings at different positions in the input string. The algorithm then iterates through this table, comparing characters and updating the lengths of repeated substrings it finds.

The main logic flow of the algorithm is as follows:

  1. Initialize the 2D table with zeros.

  2. Iterate through the table, comparing characters of the input string.

  3. When matching characters are found, update the length of the repeated substring in the table.

  4. Keep track of the maximum length of repeated substring found and its ending position.

  5. After filling the table, extract the longest repeated substring from the input string using the recorded length and position.

An important aspect of this algorithm is that it avoids overlapping substrings. This is achieved by checking if the distance between the current positions is greater than the length of the previously found repeated substring.

The code also includes a simple example usage, where it applies the function to the string “+-00+-00+-00+-0”. This demonstrates how the function can be used and what kind of output it produces.

In summary, this code provides a way to find the longest sequence of characters that repeats in a given text, which can be useful in various text processing and analysis tasks. It uses a clever approach to solve what could otherwise be a computationally expensive problem, making it efficient for longer input strings.

csdigit.lcsre.longest_repeated_substring(csd_string: str) → str[source]

Longest repeated non-overlapping substring

The longest_repeated_substring function takes a string as input and returns the longest repeated substring in the string.

Parameters:

csd_string (str) – The parameter csd_string is a string containing the CSD value

Returns:

The function longest_repeated_substring returns a string, which is the longest repeated substring in the given input string csd_string.

Examples

>>> longest_repeated_substring("+-00+-00+-00+-0")
'+-00+-0'

Module contents