lazy-scs 1.0.0__tar.gz

lazy_scs-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krushna Dere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lazy_scs-1.0.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: lazy-scs
+Version: 1.0.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+License-File: LICENSE
+Summary: Scalable factor-2 approximation for the shortest common superstring, with a certified lower bound
+Keywords: shortest common superstring,approximation algorithm,genome assembly,suffix automaton,strings
+Author: Krushna Dere, Svyatoblood
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Paper, https://github.com/nurric-ai/lazy-scs/blob/main/paper/paper.pdf
+Project-URL: Repository, https://github.com/nurric-ai/lazy-scs
+
+# lazy-scs
+
+Fast, memory-lean **factor-2 approximation for the shortest common superstring** (SCS), with a
+**certified lower bound** on the optimum. It implements the first polynomial-time factor-2
+algorithm ([openai/math result 128](https://github.com/openai/math)) using lazily enabled periodic
+rules and suffix-automaton counts, so memory grows linearly with the input (about 115 bytes per
+input character), not quadratically.
+
+```bash
+pip install lazy-scs
+```
+
+```python
+import lazy_scs
+
+lazy_scs.shortest_superstring(["GATTACA", "TACAGG", "AGGCT"])
+# 'GATTACAGGCT'
+
+r = lazy_scs.solve(reads)           # list of str or bytes
+r.superstring                       # contains every read
+r.lower_bound                       # certified: lower_bound <= OPT
+r.ratio                             # len / lower_bound; 1.0 = provably optimal
+```
+
+The output always satisfies `len(superstring) <= 2 * lower_bound <= 2 * OPT`. On large, realistic
+inputs it is usually within a fraction of a percent of the bound; on tiny adversarial inputs it can
+be further from optimal (still within the factor 2). `solve(..., verify=True)`
+re-justifies every count of the lower bound with an independent checker.
+
+Command line (one string per line, or FASTA):
+
+```bash
+lazy-scs reads.txt -o superstring.txt --verify
+```
+
+On error-free 150 bp reads at 10x coverage of the *E. coli* K-12 genome (46.4 million input
+characters) it runs in about two minutes on a laptop and returns a superstring within 0.021% of the
+certified lower bound.
+
+Paper: *Lazy Periodic Rules: A Scalable Implementation of the Factor-2 Approximation for Shortest
+Common Superstring*, Krushna Dere and Svyatoblood, independent researchers, October 2026 —
+[paper.pdf](https://github.com/nurric-ai/lazy-scs/blob/main/paper/paper.pdf). Source, the Lean 4
+formalisation of the lower-bound argument, and benchmarks: <https://github.com/nurric-ai/lazy-scs>.
+
+MIT licence.
+

lazy_scs-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["maturin>=1.7,<2"]
+build-backend = "maturin"
+
+[project]
+name = "lazy-scs"
+version = "1.0.0"
+description = "Scalable factor-2 approximation for the shortest common superstring, with a certified lower bound"
+readme = "python/README.md"
+license = { text = "MIT" }
+authors = [{ name = "Krushna Dere" }, { name = "Svyatoblood" }]
+requires-python = ">=3.9"
+keywords = ["shortest common superstring", "approximation algorithm", "genome assembly", "suffix automaton", "strings"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[project.urls]
+Repository = "https://github.com/nurric-ai/lazy-scs"
+Paper = "https://github.com/nurric-ai/lazy-scs/blob/main/paper/paper.pdf"
+
+[project.scripts]
+lazy-scs = "lazy_scs.__main__:main"
+
+[tool.maturin]
+manifest-path = "scs/scs-rs/Cargo.toml"
+python-source = "python"
+module-name = "lazy_scs._core"
+features = ["python"]
+bindings = "pyo3"
+include = [{ path = "LICENSE", format = ["sdist", "wheel"] }]

lazy_scs-1.0.0/python/README.md

@@ -0,0 +1,45 @@
+# lazy-scs
+
+Fast, memory-lean **factor-2 approximation for the shortest common superstring** (SCS), with a
+**certified lower bound** on the optimum. It implements the first polynomial-time factor-2
+algorithm ([openai/math result 128](https://github.com/openai/math)) using lazily enabled periodic
+rules and suffix-automaton counts, so memory grows linearly with the input (about 115 bytes per
+input character), not quadratically.
+
+```bash
+pip install lazy-scs
+```
+
+```python
+import lazy_scs
+
+lazy_scs.shortest_superstring(["GATTACA", "TACAGG", "AGGCT"])
+# 'GATTACAGGCT'
+
+r = lazy_scs.solve(reads)           # list of str or bytes
+r.superstring                       # contains every read
+r.lower_bound                       # certified: lower_bound <= OPT
+r.ratio                             # len / lower_bound; 1.0 = provably optimal
+```
+
+The output always satisfies `len(superstring) <= 2 * lower_bound <= 2 * OPT`. On large, realistic
+inputs it is usually within a fraction of a percent of the bound; on tiny adversarial inputs it can
+be further from optimal (still within the factor 2). `solve(..., verify=True)`
+re-justifies every count of the lower bound with an independent checker.
+
+Command line (one string per line, or FASTA):
+
+```bash
+lazy-scs reads.txt -o superstring.txt --verify
+```
+
+On error-free 150 bp reads at 10x coverage of the *E. coli* K-12 genome (46.4 million input
+characters) it runs in about two minutes on a laptop and returns a superstring within 0.021% of the
+certified lower bound.
+
+Paper: *Lazy Periodic Rules: A Scalable Implementation of the Factor-2 Approximation for Shortest
+Common Superstring*, Krushna Dere and Svyatoblood, independent researchers, October 2026 —
+[paper.pdf](https://github.com/nurric-ai/lazy-scs/blob/main/paper/paper.pdf). Source, the Lean 4
+formalisation of the lower-bound argument, and benchmarks: <https://github.com/nurric-ai/lazy-scs>.
+
+MIT licence.

lazy_scs-1.0.0/python/lazy_scs/__init__.py

@@ -0,0 +1,83 @@
+"""lazy-scs: scalable factor-2 approximation for the shortest common superstring.
+
+    >>> import lazy_scs
+    >>> lazy_scs.shortest_superstring(["GATTACA", "TACAGG", "AGGCT"])
+    'GATTACAGGCT'
+    >>> r = lazy_scs.solve(["GATTACA", "TACAGG", "AGGCT"])
+    >>> r.length, r.lower_bound, r.ratio
+    (11, 11, 1.0)
+
+The superstring always has length <= 2 * lower_bound <= 2 * OPT, and `ratio` = length / lower_bound
+is a per-instance certificate: ratio 1.0 means the output is provably optimal.
+
+Strings may be `str` (encoded as UTF-8) or `bytes`. The result has the same type as the inputs.
+The core is written in Rust and releases the GIL while it runs.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, Sequence, Union
+
+from ._core import __version__
+from ._core import solve as _solve
+
+__all__ = ["Result", "solve", "shortest_superstring", "__version__"]
+
+StrOrBytes = Union[str, bytes]
+
+
+@dataclass(frozen=True)
+class Result:
+    superstring: StrOrBytes
+    """A superstring of every input (same type as the inputs)."""
+    lower_bound: int
+    """Certified lower bound W' on the optimal length: lower_bound <= OPT <= len(superstring)."""
+    rounds: int
+    """Solver rounds (1 + number of times a lazy periodic rule had to be enabled)."""
+    stats: dict = field(default_factory=dict)
+    """Internal counters (and verify_* entries when solve(..., verify=True))."""
+
+    @property
+    def length(self) -> int:
+        return len(self.superstring)
+
+    @property
+    def ratio(self) -> float:
+        """length / lower_bound >= length / OPT: how far from optimal the output can be, at most."""
+        return self.length / self.lower_bound if self.lower_bound else 1.0
+
+
+def _encode(strings: Iterable[StrOrBytes]) -> tuple[list[bytes], bool]:
+    items = list(strings)
+    if not items:
+        return [], True
+    kinds = {type(s) for s in items}
+    if kinds <= {bytes, bytearray, memoryview}:
+        return [bytes(s) for s in items], False
+    if kinds <= {str}:
+        return [s.encode("utf-8") for s in items], True
+    raise TypeError("strings must be all str or all bytes, got " + ", ".join(sorted(k.__name__ for k in kinds)))
+
+
+def solve(strings: Sequence[StrOrBytes], *, verify: bool = False, check: bool = False) -> Result:
+    """Run the factor-2 approximation and return the superstring with its certified lower bound.
+
+    verify: re-justify every count of the lower bound from scratch (independent checker; slower).
+    check:  extra internal consistency checks while building (for debugging).
+    """
+    data, is_text = _encode(strings)
+    sup, w, _w_ext, rounds, stats = _solve(data, check=check, verify=verify)
+    if verify and (stats.get("verify_unjustified") or stats.get("verify_ext_violations")):
+        raise RuntimeError(f"lower-bound verification failed: {stats}")
+    if is_text:
+        try:
+            sup = sup.decode("utf-8")
+        except UnicodeDecodeError as e:   # overlaps are found byte-wise; only possible with non-ASCII text
+            raise ValueError("the superstring of the UTF-8 encoded inputs is not valid UTF-8; pass bytes "
+                             "instead (e.g. [s.encode() for s in strings])") from e
+    return Result(superstring=sup, lower_bound=w, rounds=rounds, stats=dict(stats))
+
+
+def shortest_superstring(strings: Sequence[StrOrBytes]) -> StrOrBytes:
+    """A superstring of all `strings` with length at most twice the optimum."""
+    return solve(strings).superstring

lazy_scs-1.0.0/python/lazy_scs/__main__.py

@@ -0,0 +1,63 @@
+"""Command line: lazy-scs INPUT [-o OUTPUT] [--verify] [--json]
+
+INPUT has one string per line, or FASTA records (any line starting with '>'); '-' reads stdin.
+Prints the superstring (or writes it to OUTPUT) and a summary line on stderr.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from . import __version__, solve
+
+
+def read_strings(text: bytes) -> list[bytes]:
+    lines = text.splitlines()
+    if any(l.startswith(b">") for l in lines):
+        out, cur = [], []
+        for l in lines:
+            if l.startswith(b">"):
+                if cur:
+                    out.append(b"".join(cur))
+                cur = []
+            else:
+                cur.append(l.strip())
+        if cur:
+            out.append(b"".join(cur))
+        return [s for s in out if s]
+    return [l.rstrip(b"\r\n") for l in lines if l.rstrip(b"\r\n")]
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="lazy-scs", description="Factor-2 approximate shortest common superstring.")
+    ap.add_argument("input", help="file with one string per line or FASTA; '-' for stdin")
+    ap.add_argument("-o", "--output", help="write the superstring here instead of stdout")
+    ap.add_argument("--verify", action="store_true", help="independently re-check the lower bound")
+    ap.add_argument("--json", action="store_true", help="print the summary as JSON on stdout (no superstring)")
+    ap.add_argument("--version", action="version", version=f"lazy-scs {__version__}")
+    a = ap.parse_args(argv)
+
+    raw = sys.stdin.buffer.read() if a.input == "-" else open(a.input, "rb").read()
+    strings = read_strings(raw)
+    t0 = time.perf_counter()
+    r = solve(strings, verify=a.verify)
+    summary = {"strings": len(strings), "input_chars": sum(map(len, strings)), "seconds": round(time.perf_counter() - t0, 3),
+               "length": r.length, "lower_bound": r.lower_bound, "ratio": round(r.ratio, 6), "rounds": r.rounds}
+    if a.verify:
+        summary["verified"] = True
+    if a.output:
+        with open(a.output, "wb") as f:
+            f.write(r.superstring)
+    if a.json:
+        print(json.dumps(summary))
+    else:
+        if not a.output:
+            sys.stdout.buffer.write(r.superstring + b"\n")
+        print(json.dumps(summary), file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lazy_scs-1.0.0/scs/scs-rs/Cargo.lock

@@ -0,0 +1,180 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a37b2691796cffeb8a8cd305ac66e65841559f147f4e63231d0eafa4db5384d1"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7778bffd85cf38175ac1f545509665d0b9b92a198ca7941f131f85f7a4f9a872"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f1b4c431c0bb1c8fb0a338709859eed0d030ff6daa34368d3b152a63dfdd8d"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fbc2201328f63c4710f68abdf653c89d8dbc2858b88c5d88b0ff38a75288a9da"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fca6726ad0f3da9c9de093d6f116a93c1a38e417ed73bf138472cf4064f72028"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "scs-rs"
+version = "1.0.0"
+dependencies = [
+ "pyo3",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

lazy_scs-1.0.0/scs/scs-rs/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "scs-rs"
+version = "1.0.0"
+edition = "2024"
+description = "Scalable factor-2 approximation for shortest common superstring (lazy periodic rules)"
+license = "MIT"
+repository = "https://github.com/nurric-ai/lazy-scs"
+
+[lib]
+name = "lazy_scs_core"
+crate-type = ["cdylib", "rlib"]
+
+[[bin]]
+name = "scs-rs"
+path = "src/main.rs"
+
+[features]
+# `python` builds the lazy_scs._core extension module (maturin, see pyproject.toml at the repo root)
+python = ["dep:pyo3"]
+
+[dependencies]
+pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"], optional = true }