bart.dias 0.9.2
Bart.dIAs: A Python assistant for identifying parallelization opportunities
Requires Python: >=3.8

**Version 0.9.1a**

Bart.dIAs is an assistant for the WebGRIPP environment. Currently, it is solely an assistante for parallel programming that analyzes sequential code to identify bottlenecks and suggest parallelization strategies. 
It combines critical path analysis with pattern recognition to provide targeted recommendations for improving application performance.


## Features

- **Critical Path Analysis**: Identifies performance bottlenecks in sequential code using directed acyclic graph (DAG) representation
- **Parallel Pattern Recognition**: Detects common parallel programming patterns in code
- **Pattern-Based Code Generation**: Automatically generates parallelized code for identified patterns (currently supporting Map-Reduce pattern)
- **Hardware-Aware Recommendations**: Provides optimization suggestions based on available system resources
- **Theoretical Performance Metrics**: Calculates work, span, and parallelism metrics based on Träff's "Lectures on Parallel Computing"
- **Partitioning Strategy Recommendations**: Suggests appropriate data and task partitioning strategies for different patterns


### Critical Path Analysis

- **DAG-Based Modeling**: Constructs a Directed Acyclic Graph (DAG) representation of code to analyze dependencies
- **Work-Span Metrics**: Calculates theoretical metrics from parallel computing theory:
    - Total Work (T₁): Sum of computational costs across all operations
    - Critical Path Length (T∞): Longest chain of dependent operations
    - Inherent Parallelism (T₁/T∞): Theoretical upper bound on speedup
- **Amdahl's Law Integration**: Estimates maximum theoretical speedup based on sequential fraction
- **Bottleneck Identification**: Pinpoints sequential code sections that limit parallelization potential


### Combo Pattern Detection

- **Complex Pattern Recognition**: Detects and analyzes advanced patterns:
    - While loops containing for loops
    - For loops with recursive function calls
    - Nested loops with varying depths
    - Loops containing function calls that themselves contain loops
    - For loops inside while loops

## New in Version 0.9.1a

- **Map-Reduce Pattern Implementation**: Added complete support for detecting and generating parallelized code for the Map-Reduce pattern
- **Hardware-Aware Code Generation**: Generated code now adapts to the actual number of processors available on the system
- **AST-Based Transformation**: Using Python's ast module for robust code analysis and transformation
- **Template-Based Code Generation**: Utilizing Jinja2 templates for readable, maintainable generated code
- **Support for Different Partitioning Strategies**: Implemented SDP (Spatial Domain Partitioning) and SIP (Spatial Instruction Partitioning) templates


## Installation

1. **Clone the repository**:

```bash
git clone https://github.com/ratem/bart.dias.git
cd bart.dias
```

2. **Install the package**:

```bash
pip install .
# Or for development mode:
pip install -e .
```

3. **Install directly from GitHub**:

```bash
pip install git+https://github.com/ratem/bart.dias.git
```


## Requirements

- Python 3.6+
- Jinja2
- NetworkX (for DAG visualization)
- Numpy
- Psutil
- Matplotlib (optional, for visualization)


## Usage

### Command-Line Interface (CLI)

You can use `bart-dias` directly from the terminal to analyze Python files:

```bash
# Analysis types: blocks, blocks_with_suggestions, critical_path, patterns, integrated
bart-dias script.py -t blocks
bart-dias script.py -t blocks_with_suggestions
bart-dias script.py -t critical_path
bart-dias script.py -t patterns
bart-dias script.py -t integrated
bart-dias script.py -t full

# Structured output (JSON for LLM consumption)
bart-dias script.py -t blocks_with_suggestions --format structured

# Line range filtering
bart-dias script.py -t blocks --start-line 50 --end-line 100

# Interactive session
bart-dias
```

### Programmatic Usage (Python Library)

You can import `bart_dias` components in your own Python projects:

```python
from bart_dias import analyze_code
import json

# Structured output — returns dict ready for LLM
result = analyze_code("script.py", analysis_type="blocks_with_suggestions", output_format="structured")
if result["ok"]:
    data = result["result"]
    # data["suggestions"][0]["code_suggestion"]  — generated parallel code
    # data["suggestions"][0]["explanation"]       — why it can be parallelized
    # data["suggestions"][0]["partitioning_suggestion"] — partitioning strategy
    prompt = f"Analyze these parallelization opportunities:\n{json.dumps(data, indent=2)}"

# Critical path with DAG + auto-detected patterns + generated code
result = analyze_code("script.py", analysis_type="critical_path", output_format="structured")
# result["result"]["metrics"]                  — work, span, parallelism, Amdahl
# result["result"]["bottlenecks"][0]["code_generation"]["transformed_code"]
# result["result"]["dag_data"]                 — nodes, edges, critical_path_nodes

# Pattern analysis with template code generation
result = analyze_code("script.py", analysis_type="patterns", output_format="structured")
# result["result"]["identified_patterns"]["map_reduce"]["code_generation"]["transformed_code"]

# Integrated analysis (critical path + patterns + codegen)
result = analyze_code("script.py", analysis_type="integrated", output_format="structured")

# Line range filtering
result = analyze_code("script.py", analysis_type="blocks", output_format="structured", start_line=50, end_line=100)

# Markdown output (for humans/CLI)
result = analyze_code("script.py", analysis_type="blocks_with_suggestions", output_format="markdown")
print(result["result"])  # formatted Markdown string
```

### Analysis Types

| Type | What it does | Structured output |
|------|-------------|-------------------|
| `blocks` | Identifies parallelizable loops, functions, comprehensions | `opportunities[]` with type, lineno |
| `blocks_with_suggestions` | Same + template-generated code per block | `suggestions[]` with `code_suggestion`, `explanation`, `partitioning_suggestion` |
| `critical_path` | DAG metrics + bottlenecks + auto-detected patterns | `metrics`, `bottlenecks[]` with `code_generation`, `dag_data` |
| `patterns` | Parallel pattern recognition + codegen | `identified_patterns{}` with `code_generation`, `performance_characteristics` |
| `integrated` | Critical path + patterns combined | All of the above combined |
| `full` | **Everything**: blocks with suggestions + integrated | `block_suggestions[]`, `metrics`, `bottlenecks[]`, `patterns{}`, `dag_data` |


## Architecture

Bart.dIAs consists of several key components:

### Core Components

1. **BDiasParser**: Parses Python code using AST analysis to identify parallelizable blocks and analyze dependencies
2. **BDiasCodeGen**: Generates parallelization suggestions using Jinja2 templates for blocks
3. **BDiasCriticalPathAnalyzer**: Performs theoretical analysis of code's inherent parallelism
4. **BDiasPatternAnalyzer**: Parses Python code using AST analysis to identify parallelizable patterns and analyze dependencies
5. **BDiasPatternCodeGen**: Generates parallelization suggestions using Jinja2 templates for patterns
6. **BDiasAssist**: Provides the user interface and coordinates the analysis process

## Theoretical Foundation

The critical path analysis is based on established parallel computing theory from Jesper Larsson Träff's "Lectures on Parallel Computing":

- **Work-Span Model**: Represents computation as a DAG where nodes are tasks and edges are dependencies
- **Critical Path Analysis**: Identifies the longest path of dependent operations that limits parallel execution
- **Amdahl's Law**: Calculates maximum theoretical speedup based on sequential fraction
- **Brent's Theorem**: Relates work, span, and processor count


## Limitations

- **Static Analysis Only**: Analysis is based on code structure, not runtime behavior
- **Focus on Multiprocessing**: Current code generation targets Python's multiprocessing module
- **Python-Specific**: Analysis is designed for Python code only
- **Theoretical Bounds**: Critical path analysis provides theoretical upper bounds that may not be achievable in practice


## Documentation

For detailed documentation, see [The Docs](https://github.com/ratem/bart.dias/tree/main/docs).

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## AI Use

This project uses AI for writing tests, docstrings, documentation, code templates, and input/output code.

## Acknowledgments

- Jesper Larsson Träff for the theoretical foundation in "Lectures on Parallel Computing"