Added readme section for kerngraph

p-isa_tools/kerngen/README.md

@@ -248,3 +248,174 @@ following
 ```bash
 pytest <test-directory>
 ```
+
+
+<!-- These contents may have been developed with support from one or more Intel-operated generative artificial intelligence solutions. -->
+
+# kerngraph.py
+
+A command-line tool for parsing and optimizing kernel strings from the kerngen.py output, with support for loop interchange and reordering optimizations.
+
+## Overview
+
+`kerngraph.py` processes kernel strings (typically generated by `kerngen.py`) and applies various optimization transformations, including loop interchange based on primary and secondary loop keys. It can work standalone or as part of a pipeline with `kerngen.py`.
+
+## Usage
+
+### Basic Pipeline
+
+The typical usage involves piping output from `kerngen.py` into `kerngraph.py`:
+
+```bash
+cat input.high | ./kerngen.py | ./kerngraph.py [OPTIONS]
+```
+where `input.high` contains input kernel lanagauge.
+
+### Standalone Usage
+
+You can also provide kernel strings directly via stdin:
+
+```bash
+./kerngraph.py [OPTIONS] < kernel_strings.txt
+```
+where `kernel_strings.txt` contains input kernel language.
+
+## Command-Line Parameters
+
+### General Options
+
+- `-d, --debug`
+  - Enable debug output for parsing errors and optimization information
+  - Shows detailed information about loop ordering decisions
+
+- `-l, --legacy`
+  - Enable legacy mode for compatibility with older kernel formats
+
+### Loop Reordering Options
+
+- `-t, --target [TARGETS...]`
+  - Specify which kernel operations to apply reordering optimizations
+  - Choices: `add`, `sub`, `mul`, `muli`, `copy`, `ntt`, `intt`, `mod`, `relin`, `rotate`, `rescale`
+  - Multiple targets can be specified (space-separated)
+  - Example: `-t relin rotate mod`
+
+- `-p, --primary {RNS,PART}`
+  - Set the primary key for loop interchange
+  - Default: `PART`
+  - Options: `RNS` (RNS-based partitioning), `PART` (partition-based)
+
+- `-s, --secondary {RNS,PART,None}`
+  - Set the secondary key for loop interchange
+  - Default: `None`
+  - Options: `RNS`, `PART`, or `None`
+  - Note: Primary and secondary keys cannot be the same
+
+- `--optimal`
+  - Automatically determine optimal primary and secondary loop order based on kernel configuration
+  - Overrides `-p` and `-s` flags
+  - Uses lookup tables based on scheme, kernel type, polynomial order, and RNS count
+
+## Input Format
+
+`kerngraph.py` expects kernel strings in the format produced by `kerngen.py`. Each line should be a valid kernel representation that can be parsed by the `KernelParser` class.
+
+## Output Format
+
+The tool outputs optimized kernel operations in p-isa format. When reordering is applied, loops are interchanged according to the specified primary and secondary keys.
+
+## Examples
+
+### Example 1: Basic Reordering
+
+Apply reordering to relin kernels with RNS as primary and PART as secondary:
+
+```bash
+cat bgv.relin.high | ./kerngen.py -l | ./kerngraph.py -l -t relin -p rns -s part
+```
+
+### Example 2: Multiple Targets
+
+Optimize multiple operation types:
+
+```bash
+cat input.high | ./kerngen.py | ./kerngraph.py -t relin rotate mod -p part -s rns
+```
+
+### Example 3: Optimal Loop Order
+
+Use automatic optimal loop ordering:
+
+```bash
+cat input.high | ./kerngen.py -l | ./kerngraph.py -l -t relin --optimal
+```
+
+### Example 4: Debug Mode
+
+Enable debug output to see optimization decisions:
+
+```bash
+cat input.high | ./kerngen.py | ./kerngraph.py -d -t relin --optimal
+```
+
+## Features
+
+### Loop Interchange Optimization
+
+The tool performs loop interchange based on the specified primary and secondary keys:
+- Splits kernels into reorderable and non-reorderable groups
+- Applies loop interchange only to reorderable sections
+- Preserves non-reorderable operations in their original order
+- Use `<reorderable>` and `</reorderable>` Comments within `kerngen` to indicate portions that are reorderable.
+
+### RNS Label Reuse
+
+When targeting `mod` operations with both primary and secondary keys specified, the tool applies RNS label reuse optimization to improve performance.
+
+### Optimal Loop Order Lookup
+
+With the `--optimal` flag, the tool automatically determines the best loop ordering based on:
+- Encryption scheme (e.g., BGV, CKKS)
+- Kernel operation type
+- Polynomial order
+- Maximum RNS count
+
+For example, a configuration file `kerngen/kernel_optimization/loop_ordering_lookup.json:
+```
+{
+  "bgv": {
+    "mod": {
+      "16384": {
+        "2-4": ["part", "null"],
+        "5-16": ["rns", "part"]
+      }
+    }
+  }
+}
+```
+will optimize bgv mod swich with poly order 16384 with priormary loop ordering when RNS is between 2-4 and primary RNS and secondary loop as part when RNS is between 5-16. The configuration file allows a developer to manually select the optimial loop reordering given encryption scheme, kernel, etc.
+
+
+## Error Handling
+
+- Invalid kernel strings are skipped with optional debug output
+- Validation ensures primary and secondary keys are different
+- Warns if optimal loop order cannot be determined (debug mode)
+
+## Integration with kerngen.py
+
+`kerngraph.py` is designed to work seamlessly with `kerngen.py`:
+
+1. `kerngen.py` reads high-level operations and generates kernel strings
+2. `kerngraph.py` parses these kernel strings and applies optimizations
+3. The output is optimized p-isa operations ready for execution
+
+## Notes
+
+- The `-l, --legacy` flag should be used consistently across both `kerngen.py` and `kerngraph.py`
+- Reordering optimizations are only applied to kernels matching the specified targets
+- Non-targeted kernels are passed through with their p-isa operations printed directly
+
+## See Also
+
+- `kerngen.py` - Kernel generator that produces input for kerngraph.py
+- `KernelParser` - Parser class for kernel string format