synkit 1.6.5__py3-none-win_amd64.whl

synkit/CRN/__init__.py

@@ -0,0 +1,233 @@
+"""Chemical reaction networks: construction, representation and analysis.
+
+``synkit.CRN`` covers the whole chain from chemistry to structural verdict:
+
+- **Construct** — expand a rule set over a seed pool into a reaction network.
+- **Query** — retrieve and curate KEGG-derived pathway data.
+- **Structure** — normalize any of the above into a :class:`SynCRN`, the
+  canonical object every other subpackage consumes.
+- **Props** — stoichiometry, conservation laws, thermodynamic and dynamical
+  summaries.
+- **Petrinet** — Petri-net view: minimal semiflows, siphons, traps, persistence.
+- **Pathway** — reachability, path finding, flow realizability.
+- **Symmetry** — canonical forms, automorphisms and isomorphism of networks.
+- **Visualize** — layout and drawing.
+- **IO** — SBML import and export for interoperability with the wider CRN
+  ecosystem.
+
+The names re-exported here are the stable public API. Anything reached by a
+deeper import path may move between releases.
+
+.. rubric:: Example
+
+.. code-block:: python
+
+    from synkit.CRN import SynCRN, PetriAnalyzer, integer_conservation_laws
+
+    crn = SynCRN.from_reaction_strings(["A>>B", "B>>A", "C>>D", "D>>C"])
+
+    print(crn)
+    print(integer_conservation_laws(crn))
+    print(PetriAnalyzer(crn, max_siphon_size=4).compute_all().summary)
+"""
+
+from __future__ import annotations
+
+from .kinds import (
+    ALL_KINDS,
+    REACTION_KINDS,
+    SPECIES_KINDS,
+    is_reaction_node,
+    is_species_node,
+    node_kind,
+)
+from .Structure import Reaction, RXNSide, Rule, Species, SynCRN
+from .Construct import (
+    ConstructionStrategy,
+    CRNExpand,
+    DerivationLog,
+    DerivationRecord,
+    DerivationState,
+    FrontierStrategy,
+    ReactionDeltaFlattener,
+    build_crn_from_smarts,
+)
+from .Props import (
+    Complex,
+    CRNTSummary,
+    StoichSummary,
+    ThermoSummary,
+    complex_graph,
+    complexes,
+    compute_thermo_summary,
+    conserved_moieties,
+    crnt_summary,
+    deficiency,
+    deficiency_one_verdict,
+    deficiency_zero_verdict,
+    integer_conservation_laws,
+    is_deficiency_one_applicable,
+    is_deficiency_zero_applicable,
+    is_reversible,
+    is_weakly_reversible,
+    left_nullspace,
+    linkage_class_deficiencies,
+    linkage_classes,
+    right_nullspace,
+    stoichiometric_matrix,
+    stoichiometric_rank,
+    strong_linkage_classes,
+    summary,
+    terminal_strong_linkage_classes,
+)
+from .Petrinet import (
+    PersistenceCheckResult,
+    PetriAnalyzer,
+    PetriNet,
+    PetriSummary,
+    find_p_semiflows,
+    find_siphons,
+    find_t_semiflows,
+    find_traps,
+    minimal_semiflows,
+    semiflow_supports,
+    siphon_persistence_condition,
+    siphon_persistence_details,
+)
+from .Pathway import (
+    PathwayFinder,
+    PathwayReachability,
+    PathwayRealizability,
+    RealizabilityResult,
+    RealizabilitySearchLimit,
+    RealizabilityStatus,
+)
+from .Symmetry import (
+    CRNCanonicalizer,
+    CRNIsomorphism,
+    CRNSymmetry,
+    SymmetryConfig,
+    are_isomorphic,
+    canonical,
+)
+from .Visualize import CRNStyle, CRNVis, draw_crn
+from .IO import crn_from_sbml, crn_to_sbml, read_sbml, write_sbml
+from .analysis import AnalysisResult, CRNAnalysis, Scenario
+from .native import (
+    build_native,
+    bundled_native_library,
+    enumerate_semiflows,
+    enumerate_structural_sets,
+)
+from .Petrinet.minimal_semiflows import SemiflowSearchLimit
+from .backend import native_backend, python_backend
+from .native_analysis import (
+    NativeSearchLimit,
+    graph_symmetry,
+    matrix_analysis,
+    qualitative_path,
+)
+
+__all__ = [
+    # node-kind vocabulary
+    "ALL_KINDS",
+    "REACTION_KINDS",
+    "SPECIES_KINDS",
+    "is_reaction_node",
+    "is_species_node",
+    "node_kind",
+    # structure
+    "SynCRN",
+    "Species",
+    "Reaction",
+    "RXNSide",
+    "Rule",
+    # construction
+    "CRNExpand",
+    "build_crn_from_smarts",
+    "ConstructionStrategy",
+    "FrontierStrategy",
+    "DerivationState",
+    "DerivationRecord",
+    "DerivationLog",
+    "ReactionDeltaFlattener",
+    # properties
+    "StoichSummary",
+    "ThermoSummary",
+    "compute_thermo_summary",
+    "conserved_moieties",
+    "integer_conservation_laws",
+    "left_nullspace",
+    "right_nullspace",
+    "stoichiometric_matrix",
+    "stoichiometric_rank",
+    "summary",
+    # CRNT
+    "Complex",
+    "CRNTSummary",
+    "complex_graph",
+    "complexes",
+    "crnt_summary",
+    "deficiency",
+    "deficiency_one_verdict",
+    "deficiency_zero_verdict",
+    "is_deficiency_one_applicable",
+    "is_deficiency_zero_applicable",
+    "is_reversible",
+    "is_weakly_reversible",
+    "linkage_class_deficiencies",
+    "linkage_classes",
+    "strong_linkage_classes",
+    "terminal_strong_linkage_classes",
+    # petri net
+    "PetriNet",
+    "PetriAnalyzer",
+    "PetriSummary",
+    "PersistenceCheckResult",
+    "find_p_semiflows",
+    "find_t_semiflows",
+    "minimal_semiflows",
+    "semiflow_supports",
+    "find_siphons",
+    "find_traps",
+    "siphon_persistence_condition",
+    "siphon_persistence_details",
+    # pathway
+    "PathwayReachability",
+    "PathwayRealizability",
+    "PathwayFinder",
+    "RealizabilityResult",
+    "RealizabilitySearchLimit",
+    "RealizabilityStatus",
+    # symmetry
+    "CRNCanonicalizer",
+    "CRNIsomorphism",
+    "CRNSymmetry",
+    "SymmetryConfig",
+    "are_isomorphic",
+    "canonical",
+    # visualization
+    "CRNStyle",
+    "CRNVis",
+    "draw_crn",
+    # interchange
+    "crn_from_sbml",
+    "crn_to_sbml",
+    "read_sbml",
+    "write_sbml",
+    # prepared analysis and native backends
+    "AnalysisResult",
+    "CRNAnalysis",
+    "Scenario",
+    "build_native",
+    "bundled_native_library",
+    "enumerate_structural_sets",
+    "enumerate_semiflows",
+    "SemiflowSearchLimit",
+    "native_backend",
+    "NativeSearchLimit",
+    "matrix_analysis",
+    "python_backend",
+    "graph_symmetry",
+    "qualitative_path",
+]

synkit/CRN/_build.py

@@ -0,0 +1,50 @@
+"""Build metadata and Boost discovery shared by native and wheel builders."""
+
+from pathlib import Path
+import sys
+
+CAPABILITIES = (
+    "closure",
+    "structural_sets",
+    "structural_unlimited",
+    "exhaustive_siphons",
+    "exact_semiflows",
+    "exact_algebra",
+    "crnt",
+    "pathway",
+    "symmetry",
+)
+
+
+def boost_include(explicit=None):
+    """Find installed headers, including an existing Conda package cache."""
+    import os
+
+    candidates = [Path(explicit)] if explicit is not None else []
+    if explicit is None:
+        if os.environ.get("BOOST_INCLUDE_DIR"):
+            candidates.append(Path(os.environ["BOOST_INCLUDE_DIR"]))
+        candidates += [
+            Path(sys.prefix) / "include",
+            Path(sys.prefix) / "Library/include",
+            Path("/usr/include"),
+            Path("/usr/local/include"),
+        ]
+        candidates += [Path("/opt/homebrew/include")]
+        for base in (sys.prefix, sys.base_prefix):
+            prefix = Path(base)
+            candidates.append(prefix / "include")
+            candidates.append(prefix / "Library/include")
+            if prefix.parent.name == "envs":
+                prefix = prefix.parent.parent
+            candidates += sorted(
+                (prefix / "pkgs").glob("libboost-headers-*/include"), reverse=True
+            )
+            candidates += sorted(
+                (prefix / "pkgs").glob("libboost-headers-*/Library/include"),
+                reverse=True,
+            )
+    return next(
+        (p for p in candidates if (p / "boost/multiprecision/cpp_int.hpp").is_file()),
+        None,
+    )

synkit/CRN/_native_build.py

@@ -0,0 +1,175 @@
+"""Explicit immutable CMake builds of the optional CRN backend."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from ._build import CAPABILITIES, boost_include
+
+
+def _digest(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def _boost_digest(include):
+    if include is None:
+        return None
+    digest = hashlib.sha256()
+    for path in sorted((include / "boost").rglob("*")):
+        if path.is_file():
+            digest.update(str(path.relative_to(include)).replace(os.sep, "/").encode())
+            digest.update(b"\0")
+            digest.update(bytes.fromhex(_digest(path)))
+    return digest.hexdigest()
+
+
+def _run(command):
+    result = subprocess.run(command, capture_output=True, text=True)
+    if result.returncode:
+        raise RuntimeError("Native CRN build failed:\n" + (result.stdout + result.stderr)[-6000:])
+    return result.stdout
+
+
+def _verify(library, exact):
+    script = """
+import ctypes, sys
+library = ctypes.CDLL(sys.argv[1])
+if library.synkit_crn_abi() != 1 or library.synkit_crn_structural_abi() != 2:
+    raise RuntimeError('Unsupported CRN structural ABI')
+for name in ('semiflows', 'algebra', 'pathway', 'symmetry'):
+    function = getattr(library, 'synkit_crn_' + name + '_abi', None)
+    if sys.argv[2] == '1':
+        if function is None or function() != 1:
+            raise RuntimeError('Unsupported CRN exact ABI: ' + name)
+    elif function is not None:
+        raise RuntimeError('Unexpected exact ABI in structural build: ' + name)
+"""
+    result = subprocess.run(
+        [sys.executable, "-c", script, str(library), str(int(exact))],
+        capture_output=True, text=True,
+    )
+    if result.returncode:
+        raise RuntimeError("Native CRN library has an incompatible ABI:\n" + result.stderr[-3000:])
+
+
+def _sources(source):
+    return {
+        str(path.relative_to(source)): path.read_bytes()
+        for path in sorted(source.rglob("*"))
+        if path.is_file() and (path.suffix in {".cpp", ".h", ".hpp", ".cmake"} or path.name == "CMakeLists.txt")
+    }
+
+
+def _configure(work, source, compiler, boost):
+    cmake = shutil.which("cmake")
+    if cmake is None:
+        raise RuntimeError("CMake is required for an explicit native CRN build")
+    command = [cmake, "-S", str(source), "-B", str(work), "-DCMAKE_BUILD_TYPE=Release",
+               "-DSYNKIT_CRN_EXACT=" + ("ON" if boost is not None else "OFF")]
+    if compiler is not None:
+        resolved = shutil.which(compiler)
+        if resolved is None:
+            raise RuntimeError(f"C++17 compiler unavailable: {compiler}")
+        command.append("-DCMAKE_CXX_COMPILER=" + resolved)
+    if boost is not None:
+        command.append("-DSYNKIT_CRN_BOOST_INCLUDE_DIR=" + str(boost))
+    _run(command)
+    prefixes = ("CMAKE_CXX_COMPILER", "CMAKE_CXX_FLAGS", "CMAKE_SHARED_LINKER_FLAGS", "CMAKE_GENERATOR",
+                "CMAKE_BUILD_TYPE", "CMAKE_OSX_", "CMAKE_VS_PLATFORM_TOOLSET")
+    cache = {}
+    for line in (work / "CMakeCache.txt").read_text().splitlines():
+        key, separator, value = line.partition("=")
+        if separator and key.startswith(prefixes):
+            cache[key] = value
+    return {"cmake": _run([cmake, "--version"]), "cmake_path": cmake, "cache": cache,
+            "compiler": json.loads((work / "crn-build.json").read_text())}
+
+
+def _reuse(library, manifest, configuration, exact):
+    try:
+        saved = json.loads(manifest.read_text())
+    except (OSError, ValueError) as exc:
+        raise RuntimeError("Existing immutable CRN library has no valid manifest") from exc
+    expected_capabilities = list(CAPABILITIES if exact else CAPABILITIES[:4])
+    if (saved.get("configuration") != configuration or saved.get("library_sha256") != _digest(library)
+            or saved.get("abi") != 1 or saved.get("semiflows_abi") != (1 if exact else None)
+            or saved.get("capabilities") != expected_capabilities):
+        raise RuntimeError("Existing immutable CRN library checksum or configuration mismatch")
+    _verify(library, exact)
+    return library
+
+
+def _publish(work, output, configuration, boost):
+    key = hashlib.sha256(json.dumps(configuration, sort_keys=True).encode()).hexdigest()
+    suffix = ".dll" if os.name == "nt" else ".dylib" if sys.platform == "darwin" else ".so"
+    library = output / ("libsynkit_crn_" + key[:16] + suffix)
+    manifest = library.with_suffix(".json")
+    if library.exists():
+        return _reuse(library, manifest, configuration, boost is not None)
+    _run([configuration["toolchain"]["cmake_path"], "--build", str(work), "--config", "Release", "--parallel", "2"])
+    candidates = list(work.rglob("*synkit_crn" + suffix))
+    if len(candidates) != 1:
+        raise RuntimeError(f"Expected one built native CRN library, found {candidates}")
+    candidate = candidates[0]
+    _verify(candidate, boost is not None)
+    if _boost_digest(boost) != configuration["boost_headers_sha256"]:
+        raise RuntimeError("Boost headers changed during the native CRN build")
+    metadata = json.loads(candidate.with_suffix(".json").read_text())
+    metadata.update(configuration=configuration, build_sha256=key, library_sha256=_digest(candidate))
+    try:
+        os.link(candidate, library)
+    except FileExistsError:
+        raise RuntimeError("Concurrent immutable CRN build installed the same artifact; rerun to verify") from None
+    manifest.write_text(json.dumps(metadata, indent=2, sort_keys=True) + "\n")
+    return library
+
+
+def build_native(output_dir, compiler=None, *, boost_include_dir=None, with_semiflows=None):
+    """Build and verify the CRN C ABI with the platform's CMake toolchain.
+
+    Exact analysis uses installed Boost headers; ``with_semiflows=False`` builds
+    only structural operations. Importing this module never invokes a compiler.
+    """
+    boost = boost_include(boost_include_dir)
+    if with_semiflows is True and boost is None:
+        raise RuntimeError(
+            "Exact native semiflows require Boost headers; supply boost_include_dir or BOOST_INCLUDE_DIR"
+        )
+    if with_semiflows is False:
+        boost = None
+    if boost is not None:
+        boost = boost.resolve()
+    source = Path(__file__).parent / "cpp"
+    payloads = _sources(source)
+    output = Path(output_dir).expanduser().resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="crn-build-", dir=output) as folder:
+        work = Path(folder)
+        snapshot = work / "sources"
+        for name, payload in payloads.items():
+            path = snapshot / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(payload)
+        build = work / "build"
+        configuration = {
+            "abi": 1, "builder_sha256": _digest(__file__),
+            "support_sha256": _digest(Path(__file__).with_name("_build.py")),
+            "sources": {name: hashlib.sha256(data).hexdigest() for name, data in payloads.items()},
+            "boost_headers_sha256": _boost_digest(boost), "platform": sys.platform, "machine": platform.machine(),
+            "environment": {
+                name: os.environ.get(name) for name in (
+                    "CXX", "CXXFLAGS", "CPPFLAGS", "LDFLAGS", "CL", "_CL_", "INCLUDE", "LIB", "LIBPATH",
+                    "SDKROOT", "MACOSX_DEPLOYMENT_TARGET", "CMAKE_GENERATOR", "CMAKE_GENERATOR_PLATFORM",
+                    "CMAKE_GENERATOR_TOOLSET", "VCToolsInstallDir", "VCToolsVersion", "WindowsSdkDir",
+                    "WindowsSDKVersion", "UniversalCRTSdkDir", "UCRTVersion",
+                )
+            },
+            "toolchain": _configure(build, snapshot, compiler, boost),
+        }
+        return _publish(build, output, configuration, boost)