Add .ptn text format for pattern serialization

.gitignore

@@ -162,6 +162,7 @@ cython_debug/
 #.idea/
 
 # Custom stuff
+examples/generated/
 docs/source/gallery
 docs/source/sg_execution_times.rst
 *.png

CHANGELOG.md

@@ -9,6 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **PTN Format**: Human-readable text format (`.ptn`) for pattern serialization
+  - `ptn_format.dumps()` / `ptn_format.dump()`: Serialize patterns to text
+  - `ptn_format.loads()` / `ptn_format.load()`: Deserialize patterns from text
+  - Format separates quantum instructions and classical feedforward processing
+  - Timeslice markers `[n]` indicate parallel execution groups
+  - Pauli measurements use compact notation (`X +`, `Y -`, `Z +`)
+  - Non-Pauli measurements use plane+angle format (`XY pi/4`)
+  - Support for node coordinates, logical observables, and inline comments
 - **Non-Unitary Parity Projection Example**: Added `examples/nonunitary_parity_projection.py` demonstrating measurement-induced entanglement via a 3-node star graph parity projector
 
 ### Fixed

docs/source/ptn_format.rst

@@ -0,0 +1,9 @@
+Pattern Text Format
+===================
+
+:mod:`graphqomb.ptn_format` module
+++++++++++++++++++++++++++++++++++
+
+.. automodule:: graphqomb.ptn_format
+   :members:
+   :member-order: bysource

docs/source/references.rst

@@ -17,6 +17,7 @@ Module reference
     focus_flow
     command
     pattern
+    ptn_format
     pauli_frame
     qompiler
     scheduler

examples/pattern_generation.py

@@ -6,7 +6,11 @@
 """
 
 # %%
+import sys
+from pathlib import Path
+
 from graphqomb.pattern import print_pattern
+from graphqomb.ptn_format import dump
 from graphqomb.qompiler import qompile
 from graphqomb.random_objects import generate_random_flow_graph
 
@@ -22,3 +26,12 @@
 print("pattern depth:", pattern.depth)
 print("pattern max space:", pattern.max_space)
 print_pattern(pattern)
+
+# Dump the pattern in GraphQOMB's text format.
+script_path = Path(globals().get("__file__", sys.argv[0])).resolve()
+example_dir = script_path.parent
+output_dir = example_dir / "generated"
+output_dir.mkdir(exist_ok=True)
+ptn_path = output_dir / "pattern_generation.ptn"
+dump(pattern, ptn_path)
+print("wrote pattern:", ptn_path)