From 5dd12e92f30ca085aaf1ff86ee44cc7039f1e23a Mon Sep 17 00:00:00 2001
From: Manuel Penschuck <penschuck@imada.sdu.dk>
Date: Mon, 24 Nov 2025 12:23:47 +0100
Subject: [PATCH 1/6] Rename dash -> hash

---
 src/binary_tree/mod.rs |  2 +-
 src/pace/reader.rs     | 16 ++++++++--------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/binary_tree/mod.rs b/src/binary_tree/mod.rs
index 33a70bf..79478c7 100644
--- a/src/binary_tree/mod.rs
+++ b/src/binary_tree/mod.rs
@@ -6,7 +6,7 @@ pub use indexed_bin_tree::*;
 pub mod depth_first_search;
 pub use depth_first_search::DepthFirstSearch;
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
 pub struct NodeIdx(pub u32);
 
 impl NodeIdx {
diff --git a/src/pace/reader.rs b/src/pace/reader.rs
index b98f8c1..9b75e8b 100644
--- a/src/pace/reader.rs
+++ b/src/pace/reader.rs
@@ -55,7 +55,7 @@ pub trait InstanceVisitor {
     fn visit_line_with_extra_whitespace(&mut self, _lineno: usize, _line: &str) -> Action {
         Action::Continue
     }
-    fn visit_unrecognized_dash_line(&mut self, _lineno: usize, _line: &str) -> Action {
+    fn visit_unrecognized_hash_line(&mut self, _lineno: usize, _line: &str) -> Action {
         Action::Continue
     }
     fn visit_unrecognized_line(&mut self, _lineno: usize, _line: &str) -> Action {
@@ -221,7 +221,7 @@ impl<'a, V: InstanceVisitor> InstanceReader<'a, V> {
                     }
                 } else {
                     // unrecognized line
-                    visit!(visit_unrecognized_dash_line, lineno, content);
+                    visit!(visit_unrecognized_hash_line, lineno, content);
                 }
                 continue;
             }
@@ -247,7 +247,7 @@ mod tests {
         pub headers: Vec<(usize, usize, usize)>,
         pub trees: Vec<(usize, String)>,
         pub extra_whitespace_lines: Vec<(usize, String)>,
-        pub unrecognized_dash_lines: Vec<(usize, String)>,
+        pub unrecognized_hash_lines: Vec<(usize, String)>,
         pub unrecognized_lines: Vec<(usize, String)>,
         pub stride_lines: Vec<(usize, String, String, String)>,
         pub param_tree_decomp: Option<(usize, TreeDecomposition)>,
@@ -269,8 +269,8 @@ mod tests {
             Action::Continue
         }
 
-        fn visit_unrecognized_dash_line(&mut self, lineno: usize, line: &str) -> Action {
-            self.unrecognized_dash_lines
+        fn visit_unrecognized_hash_line(&mut self, lineno: usize, line: &str) -> Action {
+            self.unrecognized_hash_lines
                 .push((lineno, line.to_string()));
             Action::Continue
         }
@@ -318,7 +318,7 @@ mod tests {
             vec![(1, "(1);".to_string()), (3, "(2);".to_string())]
         );
         assert!(visitor.extra_whitespace_lines.is_empty());
-        assert!(visitor.unrecognized_dash_lines.is_empty());
+        assert!(visitor.unrecognized_hash_lines.is_empty());
         assert!(visitor.unrecognized_lines.is_empty());
     }
 
@@ -339,7 +339,7 @@ mod tests {
             visitor.extra_whitespace_lines,
             vec![(1, " (1);".to_string())]
         );
-        assert!(visitor.unrecognized_dash_lines.is_empty());
+        assert!(visitor.unrecognized_hash_lines.is_empty());
         assert!(visitor.unrecognized_lines.is_empty());
     }
 
@@ -361,7 +361,7 @@ mod tests {
             vec![(1, " (1);".to_string())]
         );
         assert_eq!(
-            visitor.unrecognized_dash_lines,
+            visitor.unrecognized_hash_lines,
             vec![(4, "#<illegal comment".to_string())]
         );
         assert_eq!(

From a836fbefa5e0894dcf7553c1b4f89f088bb6a385 Mon Sep 17 00:00:00 2001
From: Manuel Penschuck <penschuck@imada.sdu.dk>
Date: Thu, 27 Nov 2025 12:04:06 +0100
Subject: [PATCH 2/6] Fix typo: leafs -> leaves

---
 src/pace/reader.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/pace/reader.rs b/src/pace/reader.rs
index 9b75e8b..9d9f6f6 100644
--- a/src/pace/reader.rs
+++ b/src/pace/reader.rs
@@ -46,7 +46,7 @@ pub struct InstanceReader<'a, V: InstanceVisitor> {
 ///
 /// Example: see the documentation of [`InstanceReader`].
 pub trait InstanceVisitor {
-    fn visit_header(&mut self, _lineno: usize, _num_trees: usize, _num_leafs: usize) -> Action {
+    fn visit_header(&mut self, _lineno: usize, _num_trees: usize, _num_leaves: usize) -> Action {
         Action::Continue
     }
     fn visit_tree(&mut self, _lineno: usize, _line: &str) -> Action {
@@ -254,8 +254,8 @@ mod tests {
     }
 
     impl InstanceVisitor for TestVisitor {
-        fn visit_header(&mut self, lineno: usize, num_trees: usize, num_leafs: usize) -> Action {
-            self.headers.push((lineno, num_trees, num_leafs));
+        fn visit_header(&mut self, lineno: usize, num_trees: usize, num_leaves: usize) -> Action {
+            self.headers.push((lineno, num_trees, num_leaves));
             Action::Continue
         }
 

From 03153925c0dca478f4754bd9568e41793b019780 Mon Sep 17 00:00:00 2001
From: Manuel Penschuck <penschuck@imada.sdu.dk>
Date: Thu, 27 Nov 2025 12:06:04 +0100
Subject: [PATCH 3/6] Add TopDownCursor::visit

---
 src/binary_tree/mod.rs           | 39 +++++++++++++++++++++++++++++++-
 src/newick/binary_tree_writer.rs | 21 +++++++++--------
 2 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/src/binary_tree/mod.rs b/src/binary_tree/mod.rs
index 79478c7..21eb244 100644
--- a/src/binary_tree/mod.rs
+++ b/src/binary_tree/mod.rs
@@ -28,11 +28,13 @@ impl From<Label> for NodeIdx {
     }
 }
 
+/// Generic interface to build binary trees required by Newick parser.
 pub trait TreeBuilder {
     type Node;
 
     /// Creates a new inner node with the two children provided.
     ///
+    ///
     /// # Example
     /// ```
     /// use pace26io::binary_tree::*;
@@ -82,9 +84,18 @@ pub trait TreeBuilder {
     }
 }
 
+pub enum NodeType<T> {
+    Inner(T, T),
+    Leaf(Label),
+}
+
+/// Minimal requirement for a binary tree implemenation (e.g., used for Newick writer).
 pub trait TopDownCursor: Sized {
     /// Returns the children iff self is an inner node and `None` otherwise.
     ///
+    /// # Remark
+    /// When traversing a tree, it is often more convenient to use [`TopDownCursor::visit`].
+    ///
     /// # Example
     /// ```
     /// use pace26io::binary_tree::*;
@@ -137,6 +148,9 @@ pub trait TopDownCursor: Sized {
 
     /// Returns the label iff self is a leaf node and `None` otherwise.
     ///
+    /// # Remark
+    /// When traversing a tree, it is often more convenient to use [`TopDownCursor::visit`].
+    ///
     /// # Example
     /// ```
     /// use pace26io::binary_tree::*;
@@ -147,7 +161,7 @@ pub trait TopDownCursor: Sized {
     ///
     /// assert_eq!(leaf.top_down().leaf_label().unwrap(), Label(1337));
     /// assert!(   root.top_down().leaf_label().is_none());
-    ///
+    /// ```
     fn leaf_label(&self) -> Option<Label>;
 
     /// Returns true iff self is an inner node
@@ -183,6 +197,29 @@ pub trait TopDownCursor: Sized {
     fn is_leaf(&self) -> bool {
         self.leaf_label().is_some()
     }
+
+    /// For an inner node returns NodeType::Inner, for a leaf returns NodeType::Leaf.
+    ///
+    /// # Example
+    /// ```
+    /// use pace26io::binary_tree::*;
+    ///
+    /// let mut builder = BinTreeBuilder::default();
+    /// let leaf = builder.new_leaf(Label(1));
+    /// let root = builder.new_inner(NodeIdx::new(0), leaf.clone(), leaf.clone());
+    ///
+    /// assert!(matches!(root.top_down().visit(), NodeType::Inner(..)));
+    /// assert!(matches!(leaf.top_down().visit(), NodeType::Leaf(..)));
+    /// ```
+    fn visit(&self) -> NodeType<Self> {
+        if let Some((l, r)) = self.children() {
+            NodeType::Inner(l, r)
+        } else if let Some(l) = self.leaf_label() {
+            NodeType::Leaf(l)
+        } else {
+            unreachable!("Each node is either an inner node or a leaf");
+        }
+    }
 }
 
 /// Tree with indexed inner nodes
diff --git a/src/newick/binary_tree_writer.rs b/src/newick/binary_tree_writer.rs
index 0532f2c..9981574 100644
--- a/src/newick/binary_tree_writer.rs
+++ b/src/newick/binary_tree_writer.rs
@@ -3,16 +3,17 @@ use std::io::Write;
 
 impl<B: TopDownCursor> NewickWriter for B {
     fn write_newick_inner(&self, writer: &mut impl Write) -> std::io::Result<()> {
-        if let Some((left, right)) = self.children() {
-            write!(writer, "(")?;
-            left.write_newick_inner(writer)?;
-            write!(writer, ",")?;
-            right.write_newick_inner(writer)?;
-            write!(writer, ")")
-        } else if let Some(Label(label)) = self.leaf_label() {
-            write!(writer, "{label}")
-        } else {
-            unreachable!("Nodes must either have children or a label; this one has neither");
+        match self.visit() {
+            NodeType::Inner(left, right) => {
+                write!(writer, "(")?;
+                left.write_newick_inner(writer)?;
+                write!(writer, ",")?;
+                right.write_newick_inner(writer)?;
+                write!(writer, ")")
+            }
+            NodeType::Leaf(Label(label)) => {
+                write!(writer, "{label}")
+            }
         }
     }
 }

From e4654b655183a8c52dfabbdf8c9d6d61038c7013 Mon Sep 17 00:00:00 2001
From: Manuel Penschuck <penschuck@imada.sdu.dk>
Date: Thu, 27 Nov 2025 12:11:20 +0100
Subject: [PATCH 4/6] Add simplified interface

---
 src/pace/mod.rs        |   1 +
 src/pace/simplified.rs | 166 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 167 insertions(+)
 create mode 100644 src/pace/simplified.rs

diff --git a/src/pace/mod.rs b/src/pace/mod.rs
index 55a2cc5..ac41fea 100644
--- a/src/pace/mod.rs
+++ b/src/pace/mod.rs
@@ -1,2 +1,3 @@
 pub mod parameters;
 pub mod reader;
+pub mod simplified;
diff --git a/src/pace/simplified.rs b/src/pace/simplified.rs
new file mode 100644
index 0000000..0f6f12a
--- /dev/null
+++ b/src/pace/simplified.rs
@@ -0,0 +1,166 @@
+use crate::{
+    binary_tree::{NodeIdx, TreeBuilder},
+    newick::{BinaryTreeParser, ParserError},
+    pace::{
+        parameters::tree_decomposition::TreeDecomposition,
+        reader::{Action, InstanceReader, InstanceVisitor, ReaderError},
+    },
+};
+use std::io::BufRead;
+
+use thiserror::Error;
+
+/// Simplified interface to read PACE26 instances and extract all information
+/// relevant for solvers. The interface is generic in [`TreeBuilder`]
+/// allowing the calling code to specify its own binary tree implementation.
+/// The only explicitly implemented function is [`Instance::try_read`]; if successful,
+/// access retrieved data directly from the struct.
+/// Future versions of this crate may add more instance parameters.
+#[derive(Debug, Clone)]
+pub struct Instance<B: TreeBuilder> {
+    pub num_leaves: usize,
+    pub trees: Vec<B::Node>,
+    pub tree_decomposition: Option<TreeDecomposition>,
+}
+
+impl<B: TreeBuilder> Instance<B> {
+    pub fn try_read(
+        reader: impl BufRead,
+        tree_builder: &mut B,
+    ) -> Result<Self, SimplifiedReaderError> {
+        let mut instance = Instance {
+            num_leaves: 0,
+            trees: Vec::with_capacity(2),
+            tree_decomposition: None,
+        };
+
+        let mut visitor = Visitor {
+            builder: tree_builder,
+            instance: &mut instance,
+            num_leaves: None,
+            error: None,
+        };
+
+        let mut instance_reader = InstanceReader::new(&mut visitor);
+        instance_reader.read(reader)?;
+
+        if let Some(err) = visitor.error {
+            return Err(err);
+        }
+
+        Ok(instance)
+    }
+}
+
+struct Visitor<'a, B: TreeBuilder> {
+    builder: &'a mut B,
+    instance: &'a mut Instance<B>,
+    num_leaves: Option<usize>,
+    error: Option<SimplifiedReaderError>,
+}
+
+impl<'a, B: TreeBuilder> InstanceVisitor for Visitor<'a, B> {
+    fn visit_header(
+        &mut self,
+        _lineno: usize,
+        _num_trees: usize,
+        num_leaves: usize,
+    ) -> super::reader::Action {
+        if self.num_leaves.is_some() {
+            self.error = Some(SimplifiedReaderError::MultipleHeaders);
+            return Action::Terminate;
+        }
+
+        if num_leaves == 0 {
+            self.error = Some(SimplifiedReaderError::NoLeaves);
+            return Action::Terminate;
+        }
+
+        self.num_leaves = Some(num_leaves);
+        self.instance.num_leaves = num_leaves;
+        Action::Continue
+    }
+
+    fn visit_tree(&mut self, _lineno: usize, line: &str) -> super::reader::Action {
+        let num_leaves = match self.num_leaves {
+            Some(x) => x,
+            None => {
+                self.error = Some(SimplifiedReaderError::NoHeader);
+                return Action::Terminate;
+            }
+        };
+
+        let root_id = (self.instance.trees.len() + 1) * (num_leaves - 1) + 2;
+
+        let tree = match self
+            .builder
+            .parse_newick_from_str(line, NodeIdx(root_id as u32))
+        {
+            Ok(t) => t,
+            Err(e) => {
+                self.error = Some(SimplifiedReaderError::NewickError(e));
+                return Action::Terminate;
+            }
+        };
+
+        self.instance.trees.push(tree);
+
+        super::reader::Action::Continue
+    }
+
+    const VISIT_PARAM_TREE_DECOMPOSITION: bool = true;
+    fn visit_param_tree_decomposition(
+        &mut self,
+        _lineno: usize,
+        td: TreeDecomposition,
+    ) -> super::reader::Action {
+        self.instance.tree_decomposition = Some(td);
+        super::reader::Action::Continue
+    }
+}
+
+#[derive(Debug, Error)]
+pub enum SimplifiedReaderError {
+    #[error(transparent)]
+    ReaderError(#[from] ReaderError),
+
+    #[error(transparent)]
+    NewickError(#[from] ParserError),
+
+    #[error(transparent)]
+    JSONError(#[from] serde_json::Error),
+
+    #[error(transparent)]
+    IO(#[from] std::io::Error),
+
+    #[error("Multiple headers found")]
+    MultipleHeaders,
+
+    #[error("Header indicates no leaves")]
+    NoLeaves,
+
+    #[error("No header before first tree")]
+    NoHeader,
+}
+
+#[cfg(test)]
+mod test {
+    use crate::binary_tree::IndexedBinTreeBuilder;
+
+    use super::*;
+    use std::{fs::File, io::BufReader};
+
+    #[test]
+    fn read_tiny() {
+        let mut input = BufReader::new(File::open("examples/tiny01.nw").unwrap());
+
+        // Parse instance
+        let mut tree_builder = IndexedBinTreeBuilder::default();
+        let instance =
+            Instance::try_read(&mut input, &mut tree_builder).expect("Valid PACE26 Instance");
+
+        assert_eq!(instance.num_leaves, 6);
+        assert_eq!(instance.trees.len(), 2);
+        assert_eq!(instance.tree_decomposition.unwrap().treewidth, 2);
+    }
+}

From d499f23264f801a47c306888e50a1235171035f2 Mon Sep 17 00:00:00 2001
From: Manuel Penschuck <penschuck@imada.sdu.dk>
Date: Thu, 27 Nov 2025 12:28:23 +0100
Subject: [PATCH 5/6] Improve documentation

---
 README.md             | 48 +++++++++++++++++++++++++++
 examples/normalize.rs | 76 +++++++++++++++++++++++++++++++++++++++++++
 examples/tiny01.nw    |  7 ++++
 src/lib.rs            |  2 ++
 4 files changed, 133 insertions(+)
 create mode 100644 README.md
 create mode 100644 examples/normalize.rs
 create mode 100644 examples/tiny01.nw

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5bc4a18
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# PACE 2026 I/O Crate
+
+This crate implements parsers and writers for the PACE 2026 file format. It was originally 
+developped for the official PACE tools (e.g., verifier and stride). As such, it offers a
+great deal of flexibility including quite pedantic parsing modes. Most users should stay
+away from this mess and rather use the simplified reader interface:
+
+## Simplified reader interface 
+
+We offer a simplified interface in [`pace::simplified::Instance`] intend to be used by solver
+implementers. To read an instance, you may use:
+
+```rust
+use std::{fs::File, io::BufReader};
+use pace26io::{binary_tree::*, newick::NewickWriter, pace::simplified::*};
+
+type Builder = IndexedBinTreeBuilder; // If you do not care about inner node indices, use BinTreeBuilder
+type Node = <Builder as TreeBuilder>::Node;
+
+// A solver would typically use `std::io::stdin().lock()` instead of reading a file
+let mut input = BufReader::new(File::open("examples/tiny01.nw").unwrap());
+
+// Parse instance
+let mut tree_builder = Builder::default();
+let instance = Instance::try_read(&mut input, &mut tree_builder)
+    .expect("Valid PACE26 Instance");
+
+println!("# Found {} trees", instance.trees.len());
+```
+
+This interface will ignore most parser warnings and only report raise errors if parsing cannot continue. We recommend the `stride` tool to debug broken instances.
+
+## Tree representation
+
+We offer only rudamentary tree representations, more specifically 
+[`binary_tree::BinTree`] and [`binary_tree::IndexedBinTree`]. The latter also stores 
+node ids of internal nodes, which are for instance used by graph parameters. 
+
+We expect that solvers will typically need more control over their data structures. 
+For this reason, the crate is designed to make implementation of own tree structures straight forward.
+You need to provide 
+ - A node type which respresents both inner nodes and leafes. It needs to implement [`binary_tree::TopDownCursor`] and --if applicable-- [`binary_tree::TreeWithNodeIdx`].
+ - A struct implementing [`binary_tree::TreeBuilder`].
+
+## Writing Newick strings
+
+A Newick String writer is provided for each data structure implementing [`binary_tree::TopDownCursor`].
+For further details see [`newick::NewickWriter`].
diff --git a/examples/normalize.rs b/examples/normalize.rs
new file mode 100644
index 0000000..22ef112
--- /dev/null
+++ b/examples/normalize.rs
@@ -0,0 +1,76 @@
+/// This example reads in an instance, orders the trees, the children of each
+/// inner node, such that the left child always contains the smallest leaf label.
+///
+/// To execute it, run `cat examples/tiny01.nw | cargo --example normalize`
+use pace26io::{binary_tree::*, newick::NewickWriter, pace::simplified::*};
+
+type Builder = IndexedBinTreeBuilder; // If you do not care about inner node indices, use BinTreeBuilder
+type Node = <Builder as TreeBuilder>::Node;
+
+fn main() {
+    let mut tree_builder = Builder::default();
+    let instance = Instance::try_read(&mut std::io::stdin().lock(), &mut tree_builder)
+        .expect("Valid PACE26 Instance");
+
+    println!("# Found {} trees", instance.trees.len());
+    if let Some(td) = instance.tree_decomposition.as_ref() {
+        println!(
+            "# Found tree decomposition with treewidth {}, {} bags, and {} edges",
+            td.treewidth,
+            td.bags.len(),
+            td.edges.len()
+        );
+    }
+
+    for (tree_id, tree) in instance.trees.iter().enumerate() {
+        let root_id = (tree_id + 1) * (instance.num_leaves - 1) + 2;
+        let normalized_tree =
+            build_normalized_tree(&mut tree_builder, tree, NodeIdx(root_id as u32));
+
+        println!("{}", normalized_tree.top_down().to_newick_string());
+    }
+}
+
+fn build_normalized_tree(
+    builder: &mut Builder,
+    node: impl TopDownCursor,
+    node_id: NodeIdx,
+) -> Node {
+    let root = build_normalized_tree_rec(builder, node, node_id).0;
+    builder.make_root(root)
+}
+
+fn build_normalized_tree_rec(
+    builder: &mut Builder,
+    node: impl TopDownCursor,
+    node_id: NodeIdx,
+) -> (Node, Label, NodeIdx) {
+    match node.visit() {
+        // Base case: For a leaf with simply copy the label and build a new leaf node
+        NodeType::Leaf(label) => (builder.new_leaf(label), label, node_id),
+
+        // Recursion into subtrees:
+        NodeType::Inner(left, right) => {
+            // recursively decent into both subtrees
+            let (child0, label0, next_node_id) =
+                build_normalized_tree_rec(builder, left, node_id.incremented());
+            let (child1, label1, next_node_id) =
+                build_normalized_tree_rec(builder, right, next_node_id);
+
+            // construct a new inner node with the smaller subtree to the left
+            if label0 < label1 {
+                (
+                    builder.new_inner(node_id, child0, child1),
+                    label0,
+                    next_node_id,
+                )
+            } else {
+                (
+                    builder.new_inner(node_id, child1, child0),
+                    label1,
+                    next_node_id,
+                )
+            }
+        }
+    }
+}
diff --git a/examples/tiny01.nw b/examples/tiny01.nw
new file mode 100644
index 0000000..f2fa395
--- /dev/null
+++ b/examples/tiny01.nw
@@ -0,0 +1,7 @@
+#s hash "0x118494c254c36869026cfc"
+#s name "tiny01"
+#s desc "Example shown on https://pacechallenge.org"
+#p 2 6
+(((5,6),(3,4)),(1,2));
+(((((4,2),1),5),3),6);
+#x treedecomp [2,[[8,16],[8,11,16],[1,11,15],[2,11,16],[7,8,11],[8,10,16],[3,10,13],[4,10,16],[8,9],[5,9,14],[6,9,12]],[[1,2],[1,6],[1,9],[2,3],[2,4],[2,5],[6,7],[6,8],[9,10],[9,11]]]
diff --git a/src/lib.rs b/src/lib.rs
index c433e63..0b42dd7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 pub mod binary_tree;
 pub mod newick;
 pub mod pace;

From 0c60989907c114f44f9557e51a6553663fa97dc3 Mon Sep 17 00:00:00 2001
From: Manuel Penschuck <penschuck@imada.sdu.dk>
Date: Thu, 27 Nov 2025 13:26:07 +0100
Subject: [PATCH 6/6] Update Cargo.toml

---
 Cargo.toml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Cargo.toml b/Cargo.toml
index b1a646c..ecdcc2b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,6 +5,9 @@ edition = "2024"
 authors = ["Manuel Penschuck"]
 description = "Utilities to read PACE26 instances and write answers"
 license = "GPL-3.0-or-later"
+repository = "https://github.com/manpen/pace26io"
+homepage = "https://pacechallenge.org/2026/"
+exclude = ["/.github"]
 
 [dependencies]
 serde = "1.0.228"