From 0c66bdce0fd881ad71ff02de08e07438e9f87a35 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 11:35:25 +0000 Subject: [PATCH 1/4] Initial plan From 0d75f854888bac9eeaa57e19aba2824bc16d63b7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 11:39:19 +0000 Subject: [PATCH 2/4] Add comprehensive documentation with usage examples Co-authored-by: mmirko <7934656+mmirko@users.noreply.github.com> --- README.md | 303 +++++++++++++++++++++++++++++++- examples/README.md | 100 +++++++++++ examples/complex_expression.txt | 6 + examples/example_config.json | 6 + examples/matrix_operations.txt | 9 + examples/polynomial.txt | 6 + examples/simple_addition.txt | 6 + examples/trigonometric.txt | 6 + 8 files changed, 440 insertions(+), 2 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/complex_expression.txt create mode 100644 examples/example_config.json create mode 100644 examples/matrix_operations.txt create mode 100644 examples/polynomial.txt create mode 100644 examples/simple_addition.txt create mode 100644 examples/trigonometric.txt diff --git a/README.md b/README.md index 771e10c..a836607 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,302 @@ -# flexpy +# Flexpy - FPGA Logic from EXpressions in Python -flexpy is a Python package for converting symbolic mathematical expressions created with the sympy library to BondMachine basm code. \ No newline at end of file +Flexpy is a Python package for converting symbolic mathematical expressions created with the SymPy library to BondMachine BASM code or HLS (High-Level Synthesis) code. It enables automatic generation of FPGA logic circuits from mathematical expressions. + +## Features + +- Convert SymPy symbolic expressions to BondMachine BASM code +- Convert SymPy expressions to HLS code +- Support for various data types (float32, float64, custom types via bmnumbers) +- Matrix and tensor operations support +- Complex number support +- Device-specific code generation +- Configurable via JSON configuration files +- Support for both synchronous and asynchronous I/O modes + +## Prerequisites + +Before using Flexpy, you need to have: + +1. **Python 3.x** installed +2. **bmnumbers** executable available in your PATH - This is a BondMachine tool required for type system operations + - Used to get size, prefix, and supported operations for different numeric types + - Without this, Flexpy will exit with an error + +## Installation + +### From Source + +1. Clone the repository: +```bash +git clone https://github.com/BondMachineHQ/flexpy.git +cd flexpy +``` + +2. Install dependencies: +```bash +pip install -r requirements.txt +``` + +3. (Optional) Build the standalone executable: +```bash +make package +``` + +### Dependencies + +Flexpy requires the following Python packages: +- `sympy` - Symbolic mathematics library +- `numpy` - Numerical computing library +- `docopt` - Command-line argument parsing +- `jinja2` - Template engine for code generation +- `pyinstaller` - For building standalone executable (optional) + +## Quick Start + +### Basic Usage + +1. Create an expression file (e.g., `simple_expr.txt`): +```python +import sympy as sp +x, y = sp.symbols('x y') +spExpr = x + y +testRanges = None +``` + +2. Convert to BASM: +```bash +python flexpy.py -e simple_expr.txt -o output.basm --basm +``` + +3. Convert to HLS: +```bash +python flexpy.py -e simple_expr.txt -o output.hls --hls +``` + +## Command-Line Options + +``` +Usage: + flexpy -e -o (--basm | --hls) [-d] [--config-file ] + [-r ] [-t ] [--build-app] [--app-file ] + [--emit-bmapi-maps] [--bmapi-maps-file ] [--io-mode ] + [--neuron-statistics ] [--devices ] + flexpy -e --iomap-only --basm [-d] [--config-file ] + flexpy -h | --help + +Options: + -h --help Show help screen + -e Expression file to convert + -o Output file path + --basm Convert to BASM format + --hls Convert to HLS format + -d Enable debug mode + -r , --register-size Register size (required for variable-size types) + -t , --data-type Data type (default: float32) + --config-file JSON configuration file + --build-app Build application wrapper + --app-file Application file output path + --emit-bmapi-maps Emit BondMachine API maps + --bmapi-maps-file BMAPI maps output file + --io-mode I/O mode: sync or async (default: sync) + --iomap-only Generate only I/O mapping + --neuron-statistics Save neuron statistics to JSON file + --devices Comma-separated list of target devices +``` + +## Expression File Format + +Expression files are Python scripts that define symbolic expressions using SymPy. They must define: + +- `spExpr`: The main symbolic expression (can be a scalar, matrix, or tensor) +- `testRanges`: Optional test ranges for validation (can be None) + +### Example 1: Simple Expression + +```python +import sympy as sp + +x, y, z = sp.symbols('x y z') +spExpr = x * y + z +testRanges = None +``` + +### Example 2: Matrix Expression + +```python +import sympy as sp +import numpy as np + +x, y = sp.symbols('x y') +# Create a 2x2 matrix +spExpr = sp.Matrix([[x + y, x - y], + [x * y, x / y]]) +testRanges = None +``` + +### Example 3: Complex Expression + +```python +import sympy as sp + +x = sp.Symbol('x') +# Expression with sine and cosine +spExpr = sp.sin(x) * sp.cos(x) +testRanges = None +``` + +### Example 4: Using Devices + +```python +import sympy as sp + +x, y = sp.symbols('x y') +# Define device functions (must be declared in --devices) +device1 = sp.Function('device1') +device2 = sp.Function('device2') + +spExpr = device1(x) + device2(y) +testRanges = None +``` + +Run with: +```bash +python flexpy.py -e expr.txt -o output.basm --basm --devices device1,device2 +``` + +## Configuration Files + +Configuration files are JSON files that can specify custom parameters for code generation. + +### Example Configuration + +```json +{ + "params": { + "param1": "value1", + "param2": "value2" + } +} +``` + +Usage: +```bash +python flexpy.py -e expr.txt -o output.basm --basm --config-file config.json +``` + +## Data Types + +Flexpy supports various numeric types through the `bmnumbers` tool. Common types include: + +- `float32` (default) - 32-bit floating-point +- `float64` - 64-bit floating-point +- Custom types defined in BondMachine + +To specify a data type: +```bash +python flexpy.py -e expr.txt -o output.basm --basm -t float64 +``` + +For variable-size types, you must also specify the register size: +```bash +python flexpy.py -e expr.txt -o output.basm --basm -t custom_type -r 64 +``` + +## Advanced Features + +### Debug Mode + +Enable debug mode to see detailed information about input/output mappings: +```bash +python flexpy.py -e expr.txt -o output.basm --basm -d +``` + +### I/O Modes + +Flexpy supports two I/O modes: +- `sync` (default) - Synchronous I/O +- `async` - Asynchronous I/O + +```bash +python flexpy.py -e expr.txt -o output.basm --basm --io-mode async +``` + +### Getting Only I/O Mapping + +To see the input/output mapping without generating code: +```bash +python flexpy.py -e expr.txt --iomap-only --basm +``` + +### Neuron Statistics + +Save statistics about neurons used in the computation: +```bash +python flexpy.py -e expr.txt -o output.basm --basm --neuron-statistics stats.json +``` + +### Building Applications + +Generate a complete application with API wrapper: +```bash +python flexpy.py -e expr.txt -o output.basm --basm --build-app --app-file app.c +``` + +### BMAPI Maps + +Generate BondMachine API mapping files: +```bash +python flexpy.py -e expr.txt -o output.basm --basm --emit-bmapi-maps --bmapi-maps-file maps.json +``` + +## Output Formats + +### BASM Output + +BASM (BondMachine Assembly) is the native assembly language for BondMachine. The output includes: +- Register size metadata +- I/O mode configuration +- Processor definitions +- Link definitions for connecting processors +- Input/output mappings + +### HLS Output + +HLS (High-Level Synthesis) output generates code suitable for hardware synthesis tools. + +## Examples + +See the `tests/` directory for additional examples: +- `tests/demo_tree_printing.py` - Demonstrates expression tree visualization +- `tests/test_unimplemented_tree.py` - Tests for unimplemented functions +- `qiskit-symb-test/` - Quantum circuit example using Qiskit + +## Troubleshooting + +### "Error: bmnumbers executable not found" + +Make sure the `bmnumbers` tool is installed and available in your system PATH. This is a required BondMachine component. + +### "Error: the type is not supported" + +The specified data type is not recognized by `bmnumbers`. Check available types with: +```bash +bmnumbers --help +``` + +### "Unimplemented: [function] is not supported" + +The specified SymPy function is not yet implemented in Flexpy's BASM or HLS engine. Check the error output for a detailed expression tree showing where the unsupported function appears. + +## Related Projects + +- [BondMachine](https://bondmachine.fisica.unipg.it/) - The BondMachine project +- [SymPy](https://www.sympy.org/) - Symbolic mathematics library + +## License + +This project is licensed under the Apache License 2.0 - see the LICENSE file for details. + +## Author + +Copyright 2025 - Mirko Mariotti - https://www.mirkomariotti.it \ No newline at end of file diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..16ad947 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,100 @@ +# Flexpy Examples + +This directory contains example expression files demonstrating various features of Flexpy. + +## Example Files + +### simple_addition.txt +Basic addition of two variables. Good starting point for learning Flexpy. + +**Usage:** +```bash +python ../flexpy.py -e simple_addition.txt -o simple_addition.basm --basm +``` + +### polynomial.txt +Polynomial expression demonstrating power and multiplication operations. + +**Usage:** +```bash +python ../flexpy.py -e polynomial.txt -o polynomial.basm --basm +``` + +### trigonometric.txt +Trigonometric functions (sine and cosine). + +**Usage:** +```bash +python ../flexpy.py -e trigonometric.txt -o trigonometric.basm --basm +``` + +### matrix_operations.txt +Matrix operations example showing how to work with matrices in Flexpy. + +**Usage:** +```bash +python ../flexpy.py -e matrix_operations.txt -o matrix_operations.basm --basm +``` + +### complex_expression.txt +Complex expression combining multiple operations including square root. + +**Usage:** +```bash +python ../flexpy.py -e complex_expression.txt -o complex_expression.basm --basm +``` + +## Configuration File + +### example_config.json +Example JSON configuration file showing how to pass custom parameters. + +**Usage:** +```bash +python ../flexpy.py -e simple_addition.txt -o output.basm --basm --config-file example_config.json +``` + +## Running Examples + +From the examples directory: + +```bash +# Generate BASM output +python ../flexpy.py -e simple_addition.txt -o output.basm --basm + +# Generate HLS output +python ../flexpy.py -e simple_addition.txt -o output.hls --hls + +# With debug mode +python ../flexpy.py -e simple_addition.txt -o output.basm --basm -d + +# With custom data type +python ../flexpy.py -e simple_addition.txt -o output.basm --basm -t float64 + +# Get only I/O mapping +python ../flexpy.py -e simple_addition.txt --iomap-only --basm +``` + +## Creating Your Own Examples + +To create a new expression file: + +1. Create a `.txt` file with Python code +2. Import necessary libraries (sympy, numpy) +3. Define symbolic variables using `sp.symbols()` +4. Set `spExpr` to your expression +5. Set `testRanges = None` (or define custom test ranges) + +Example template: +```python +import sympy as sp + +# Define your variables +x, y = sp.symbols('x y') + +# Define your expression +spExpr = x + y # Replace with your expression + +# Test ranges (optional) +testRanges = None +``` diff --git a/examples/complex_expression.txt b/examples/complex_expression.txt new file mode 100644 index 0000000..db227e1 --- /dev/null +++ b/examples/complex_expression.txt @@ -0,0 +1,6 @@ +import sympy as sp + +# Complex expression with multiple operations +a, b, c = sp.symbols('a b c') +spExpr = (a + b) * c + sp.sqrt(a*b) - c**2 +testRanges = None diff --git a/examples/example_config.json b/examples/example_config.json new file mode 100644 index 0000000..560e3b1 --- /dev/null +++ b/examples/example_config.json @@ -0,0 +1,6 @@ +{ + "params": { + "optimization_level": "2", + "target_platform": "bondmachine" + } +} diff --git a/examples/matrix_operations.txt b/examples/matrix_operations.txt new file mode 100644 index 0000000..d5a1ca2 --- /dev/null +++ b/examples/matrix_operations.txt @@ -0,0 +1,9 @@ +import sympy as sp + +# Matrix operations +x, y, z, w = sp.symbols('x y z w') + +# 2x2 matrix +spExpr = sp.Matrix([[x + y, x - y], + [z * w, z + w]]) +testRanges = None diff --git a/examples/polynomial.txt b/examples/polynomial.txt new file mode 100644 index 0000000..e532fc4 --- /dev/null +++ b/examples/polynomial.txt @@ -0,0 +1,6 @@ +import sympy as sp + +# Polynomial expression: x^2 + 2*x*y + y^2 +x, y = sp.symbols('x y') +spExpr = x**2 + 2*x*y + y**2 +testRanges = None diff --git a/examples/simple_addition.txt b/examples/simple_addition.txt new file mode 100644 index 0000000..7d66d0f --- /dev/null +++ b/examples/simple_addition.txt @@ -0,0 +1,6 @@ +import sympy as sp + +# Simple addition of two variables +x, y = sp.symbols('x y') +spExpr = x + y +testRanges = None diff --git a/examples/trigonometric.txt b/examples/trigonometric.txt new file mode 100644 index 0000000..3b3884c --- /dev/null +++ b/examples/trigonometric.txt @@ -0,0 +1,6 @@ +import sympy as sp + +# Trigonometric expression +x = sp.Symbol('x') +spExpr = sp.sin(x) + sp.cos(x) +testRanges = None From 87669e40c624ded862b50a89cda6ac9351f777ea Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 11:41:19 +0000 Subject: [PATCH 3/4] Address code review feedback - improve documentation clarity Co-authored-by: mmirko <7934656+mmirko@users.noreply.github.com> --- README.md | 10 ++++--- examples/README.md | 65 +++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 64 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index a836607..f89c685 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,8 @@ Before using Flexpy, you need to have: 1. **Python 3.x** installed 2. **bmnumbers** executable available in your PATH - This is a BondMachine tool required for type system operations - Used to get size, prefix, and supported operations for different numeric types - - Without this, Flexpy will exit with an error + - Part of the BondMachine toolchain - visit [BondMachine](https://bondmachine.fisica.unipg.it/) for installation instructions + - Without this tool, Flexpy will exit with an error message ## Installation @@ -77,9 +78,10 @@ python flexpy.py -e simple_expr.txt -o output.hls --hls ``` Usage: - flexpy -e -o (--basm | --hls) [-d] [--config-file ] - [-r ] [-t ] [--build-app] [--app-file ] - [--emit-bmapi-maps] [--bmapi-maps-file ] [--io-mode ] + flexpy -e -o (--basm | --hls) [-d] + [--config-file ] [-r ] [-t ] [--build-app] + [--app-file ] [--emit-bmapi-maps] + [--bmapi-maps-file ] [--io-mode ] [--neuron-statistics ] [--devices ] flexpy -e --iomap-only --basm [-d] [--config-file ] flexpy -h | --help diff --git a/examples/README.md b/examples/README.md index 16ad947..f8f47d3 100644 --- a/examples/README.md +++ b/examples/README.md @@ -7,7 +7,12 @@ This directory contains example expression files demonstrating various features ### simple_addition.txt Basic addition of two variables. Good starting point for learning Flexpy. -**Usage:** +**Usage (from repository root):** +```bash +python flexpy.py -e examples/simple_addition.txt -o simple_addition.basm --basm +``` + +**Usage (from examples directory):** ```bash python ../flexpy.py -e simple_addition.txt -o simple_addition.basm --basm ``` @@ -15,7 +20,12 @@ python ../flexpy.py -e simple_addition.txt -o simple_addition.basm --basm ### polynomial.txt Polynomial expression demonstrating power and multiplication operations. -**Usage:** +**Usage (from repository root):** +```bash +python flexpy.py -e examples/polynomial.txt -o polynomial.basm --basm +``` + +**Usage (from examples directory):** ```bash python ../flexpy.py -e polynomial.txt -o polynomial.basm --basm ``` @@ -23,7 +33,12 @@ python ../flexpy.py -e polynomial.txt -o polynomial.basm --basm ### trigonometric.txt Trigonometric functions (sine and cosine). -**Usage:** +**Usage (from repository root):** +```bash +python flexpy.py -e examples/trigonometric.txt -o trigonometric.basm --basm +``` + +**Usage (from examples directory):** ```bash python ../flexpy.py -e trigonometric.txt -o trigonometric.basm --basm ``` @@ -31,7 +46,12 @@ python ../flexpy.py -e trigonometric.txt -o trigonometric.basm --basm ### matrix_operations.txt Matrix operations example showing how to work with matrices in Flexpy. -**Usage:** +**Usage (from repository root):** +```bash +python flexpy.py -e examples/matrix_operations.txt -o matrix_operations.basm --basm +``` + +**Usage (from examples directory):** ```bash python ../flexpy.py -e matrix_operations.txt -o matrix_operations.basm --basm ``` @@ -39,7 +59,12 @@ python ../flexpy.py -e matrix_operations.txt -o matrix_operations.basm --basm ### complex_expression.txt Complex expression combining multiple operations including square root. -**Usage:** +**Usage (from repository root):** +```bash +python flexpy.py -e examples/complex_expression.txt -o complex_expression.basm --basm +``` + +**Usage (from examples directory):** ```bash python ../flexpy.py -e complex_expression.txt -o complex_expression.basm --basm ``` @@ -49,14 +74,40 @@ python ../flexpy.py -e complex_expression.txt -o complex_expression.basm --basm ### example_config.json Example JSON configuration file showing how to pass custom parameters. -**Usage:** +**Usage (from repository root):** +```bash +python flexpy.py -e examples/simple_addition.txt -o output.basm --basm --config-file examples/example_config.json +``` + +**Usage (from examples directory):** ```bash python ../flexpy.py -e simple_addition.txt -o output.basm --basm --config-file example_config.json ``` ## Running Examples -From the examples directory: +**Note:** Commands can be run from either the repository root or the examples directory. + +### From the repository root: + +```bash +# Generate BASM output +python flexpy.py -e examples/simple_addition.txt -o output.basm --basm + +# Generate HLS output +python flexpy.py -e examples/simple_addition.txt -o output.hls --hls + +# With debug mode +python flexpy.py -e examples/simple_addition.txt -o output.basm --basm -d + +# With custom data type +python flexpy.py -e examples/simple_addition.txt -o output.basm --basm -t float64 + +# Get only I/O mapping +python flexpy.py -e examples/simple_addition.txt --iomap-only --basm +``` + +### From the examples directory: ```bash # Generate BASM output From 42c42c84043fb455e724f3b3128875a10b14b253 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 14 Dec 2025 11:42:26 +0000 Subject: [PATCH 4/4] Fix documentation references and clarify numpy usage Co-authored-by: mmirko <7934656+mmirko@users.noreply.github.com> --- README.md | 9 ++++++++- examples/README.md | 17 ++++++++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f89c685..b6960a2 100644 --- a/README.md +++ b/README.md @@ -268,7 +268,14 @@ HLS (High-Level Synthesis) output generates code suitable for hardware synthesis ## Examples -See the `tests/` directory for additional examples: +See the `examples/` directory for practical examples to get started: +- `examples/simple_addition.txt` - Basic addition of two variables +- `examples/polynomial.txt` - Polynomial expression with powers +- `examples/trigonometric.txt` - Trigonometric functions +- `examples/matrix_operations.txt` - 2x2 matrix operations +- `examples/complex_expression.txt` - Complex multi-operation expression + +See the `tests/` directory for additional advanced examples: - `tests/demo_tree_printing.py` - Demonstrates expression tree visualization - `tests/test_unimplemented_tree.py` - Tests for unimplemented functions - `qiskit-symb-test/` - Quantum circuit example using Qiskit diff --git a/examples/README.md b/examples/README.md index f8f47d3..e9f586c 100644 --- a/examples/README.md +++ b/examples/README.md @@ -131,7 +131,7 @@ python ../flexpy.py -e simple_addition.txt --iomap-only --basm To create a new expression file: 1. Create a `.txt` file with Python code -2. Import necessary libraries (sympy, numpy) +2. Import sympy (and optionally numpy if needed for arrays) 3. Define symbolic variables using `sp.symbols()` 4. Set `spExpr` to your expression 5. Set `testRanges = None` (or define custom test ranges) @@ -149,3 +149,18 @@ spExpr = x + y # Replace with your expression # Test ranges (optional) testRanges = None ``` + +Example with numpy (for tensors): +```python +import sympy as sp +import numpy as np + +# Define variables +x, y = sp.symbols('x y') + +# Create a tensor expression +arr = np.array([[x, y], [y, x]]) +spExpr = sp.Array(arr) + +testRanges = None +```