graph-evolution-tool 0.9.0__cp38-abi3-win_amd64.whl

get/__init__.py

@@ -0,0 +1,12 @@
+# Re-exports the compiled extension module so `import get` gives the classes
+# directly rather than `get.get.GraphEvolver`.
+#
+# maturin generates exactly this file when the package has no Python source of
+# its own. It is written out here because the package now *does* have Python
+# source — `py.typed` and `__init__.pyi`, which an editor needs beside the
+# module — and declaring `python-source` means maturin stops generating it.
+from .get import *
+
+__doc__ = get.__doc__
+if hasattr(get, "__all__"):
+    __all__ = get.__all__

get/__init__.pyi

@@ -0,0 +1,680 @@
+"""Type stubs for `get`, generated by `tools/generate_stubs.py`.
+
+Regenerate with `maturin develop --release && python3 tools/generate_stubs.py`.
+Type annotations here are written by hand and survive regeneration; everything
+else comes from the built module.
+"""
+
+from typing import Callable
+
+__all__ = ['GraphEvolver', 'Config', 'EvolutionConfig', 'ReplacementConfig', 'ScopeConfig', 'SelectionConfig', 'CrossoverConfig', 'EdgeEditMutationConfig', 'SdaMutationConfig', 'GenomeConfig', 'FitnessConfig', 'SirParams', 'OperationWeights', 'RunResult', 'GenerationStats']
+
+class GraphEvolver:
+    """Python-facing entry point to the graph-evolution engine.
+
+    Constructed from a `config.toml` path; `run` dispatches on the configured
+    evolution strategy, genome representation and fitness objective.
+
+    **It holds no results.** A run's state lives in the `RunResult` that `run`
+    returns, so one evolver drives repeated runs with nothing stale from the
+    previous one hanging off it.
+    """
+    def __init__(self, config_path: str) -> None:
+        ...
+    @staticmethod
+    def from_config(config: Config) -> GraphEvolver:
+        """Build from configuration assembled in Python, rather than from a file.
+
+        Accepts exactly what a `config.toml` would, and reports a rejection in
+        the same words. Every block is its own object — `EvolutionConfig`,
+        `ScopeConfig`, `SelectionConfig`, `GenomeConfig`, `FitnessConfig` — and
+        all of them are required.
+
+        A field too large for a TOML integer is rejected here, which a
+        `config.toml` writer never meets.
+        """
+        ...
+    def load_reference_graphs(self, folder: str, min_node_index: int=0) -> list[tuple[str, int, list[tuple[int, int, int]]]]:
+        """Read a folder of graphs, one file per graph, and hand them back.
+
+        The bulk counterpart to `set_base_graph_from_file`, for reference data an
+        objective matches against. Each file is one edge per line,
+        `start,end,weight`, and every file in the folder shares this run's node
+        numbering.
+
+        **A reference graph may be larger than the network being evolved**, and
+        usually is — the only ceiling is a sanity bound against a file indexed
+        the wrong way.
+
+        Each graph comes back as `(name, num_nodes, edges)`, **sorted by file
+        name**, because a reference set is consumed positionally and filesystem
+        order would let a run's numbers depend on how its data was written to
+        disk. The node count is stated rather than derived: an isolated node
+        appears in no edge, so each file declares its own in a `# nodes = N`
+        header. Sub-directories are skipped; every other file is read.
+
+        **This call declares the run's numbering** as the base-graph setters do.
+        The reference graphs themselves come back exactly as supplied.
+
+        A rejection names the file and the line; the warnings are the base-graph
+        loader's, each naming the file it came from.
+        """
+        ...
+    def run(self, seed: int, n_runs: int=1, max_cores: int | None=None) -> list[RunResult]:
+        """Evolve a population `n_runs` times and return what every run produced.
+
+        **Always a list, one `RunResult` per replicate, in run order** — even at
+        the default `n_runs = 1`, so the return type does not change shape with
+        an argument.
+
+        **One master seed, not `n` of them**, so a run's seed does not depend on
+        how many were requested: asking for 50 reproduces the first 30 of a
+        30-run request exactly.
+
+        **Whether replicates run concurrently is the engine's call, not yours.**
+        A native Rust objective runs them in parallel; `fitness = "python"` runs
+        them one at a time, since concurrent runs would contend for a single GIL.
+        `max_cores` caps the concurrency; unset means all available.
+
+        A replicate that fails abandons the remaining runs rather than returning
+        half-complete.
+
+        # Memory: the sizes multiply, they do not add
+
+        The whole population is materialized before scoring, and a graph is a
+        **dense** matrix however sparse it actually is, so peak memory is roughly
+        `network_size² × 4 bytes × population_size × min(max_cores, replicates)`.
+        Raising any one of them scales the whole product.
+        """
+        ...
+    def set_base_graph(self, num_nodes: int, edges: list[tuple[int, int, int]], min_node_index: int=0) -> None:
+        """Seed an edge-edit run from a graph the caller already has.
+
+        `edges` is `(u, v, multiplicity)` — the same shape `run` hands back as
+        `best_edges`, so one run's output feeds the next without reshaping.
+
+        **One run has one numbering.** `min_node_index` is where the caller's
+        own numbering starts — pass `1` for 1-indexed edges. Every loader on this
+        evolver must declare the same one, and it is what results are shifted
+        back into, so they return in the numbering the data arrived in.
+
+        **Left unset, every run starts from an empty graph.** Several edit
+        opcodes need existing structure to walk, so early generations do little
+        until `Add` and `Toggle` have built some. That is self-correcting.
+
+        A rejected edge raises `ValueError` naming the index as the caller wrote
+        it, not as it would be after shifting. A pair given more than once is a
+        `UserWarning` and the **last** occurrence wins, compared canonically, so
+        `(2, 5)` and `(5, 2)` are one undirected edge.
+        """
+        ...
+    def set_base_graph_from_file(self, path: str, min_node_index: int=0) -> None:
+        """Seed an edge-edit run from an edge-list file, rather than from a list
+        built in Python.
+
+        One edge per line, `start,end,weight`, comma-delimited, any line ending.
+        `min_node_index` is where the caller's own node numbering starts — pass
+        `1` for 1-indexed data, which is the common case in graph files.
+        1-indexed in is 1-indexed out.
+
+        A `# nodes = N` header is mandatory and must agree with `network_size`;
+        a file with no header is rejected rather than assumed to match it.
+
+        **Nothing is stored unless the whole file survives**, and a rejection
+        names the line it came from. A repeated edge, a zero-weight edge and an
+        empty file are each a `UserWarning` rather than an error.
+        """
+        ...
+    def set_fitness_function(self, callable: Callable[..., float], direction: str) -> None:
+        """Register a Python callable as the objective, with the direction it is
+        meant to be optimized in.
+
+        `config.toml` only *selects* Python — `[fitness] type = "python"`. The
+        callable itself arrives here, and so does its direction: nothing can
+        infer whether a user's function wants its value large or small.
+
+        The callable takes the **whole batch** and returns one float per graph,
+        in the same order:
+
+        A batch element is `(num_nodes, edges)`, and `direction` is
+        `"minimize"` or `"maximize"`.
+
+        Registering a callable when the config did not select Python is a
+        `ValueError`, not a silent no-op.
+        """
+        ...
+
+class Config:
+    """Everything the genetic algorithm needs for a run."""
+    def __init__(self, evolution: EvolutionConfig, population_size: int, network_size: int, crossover_rate: float, mutation_rate: float, scope: ScopeConfig, selection: SelectionConfig, genome: GenomeConfig, fitness: FitnessConfig, max_edge_multiplicity: int=1, max_mutations: int=1, crossover: CrossoverConfig | None=None) -> None:
+        ...
+    @property
+    def crossover(self) -> CrossoverConfig:
+        """Recombination operator; two-point when unset."""
+        ...
+    @property
+    def crossover_rate(self) -> float:
+        """Probability that a selected pair is recombined."""
+        ...
+    @property
+    def evolution(self) -> EvolutionConfig:
+        """Which evolution strategy to run."""
+        ...
+    @property
+    def fitness(self) -> FitnessConfig:
+        """Fitness objective."""
+        ...
+    @property
+    def genome(self) -> GenomeConfig:
+        """Genome representation and its dimensions."""
+        ...
+    @property
+    def max_edge_multiplicity(self) -> int:
+        """Edge-weight cap; 1 is unweighted."""
+        ...
+    @property
+    def max_mutations(self) -> int:
+        """How many mutations a mutating child takes, drawn uniformly from
+        `1..=max_mutations`.
+        """
+        ...
+    @property
+    def mutation_rate(self) -> float:
+        """Probability that a child is mutated at all."""
+        ...
+    @property
+    def network_size(self) -> int:
+        """Number of nodes in every expressed graph."""
+        ...
+    @property
+    def population_size(self) -> int:
+        """Number of individuals in the population."""
+        ...
+    @property
+    def scope(self) -> ScopeConfig:
+        """Which slice of the population one breeding event draws from."""
+        ...
+    @property
+    def selection(self) -> SelectionConfig:
+        """Parent-selection strategy, applied within that scope."""
+        ...
+    def to_toml(self) -> str:
+        """Render this config as the TOML document GET parses — the record of what
+        was run, byte for byte.
+
+        `ValueError` if a field is too large for a TOML integer, `2**63 - 1`.
+        """
+        ...
+
+class EvolutionConfig:
+    """Which evolution strategy to run, and its strategy-specific settings."""
+
+    class Generational(EvolutionConfig):
+        """Whole-population replacement, run `num_generations` times."""
+        def __init__(self, num_generations: int, elite_count: int=1) -> None:
+            ...
+        @property
+        def elite_count(self) -> int:
+            """Best individuals carried forward untouched each generation.
+
+            Must be less than `population_size` — equal would mean nothing ever
+            changes.
+            """
+            ...
+        @property
+        def num_generations(self) -> int:
+            """Whole-population replacements to run."""
+            ...
+
+    class SteadyState(EvolutionConfig):
+        """Single breeding events, `num_mating_events` of them.
+
+        One event touches one scope, not the whole population.
+        """
+        def __init__(self, num_mating_events: int, replacement: ReplacementConfig | None=None) -> None:
+            ...
+        @property
+        def num_mating_events(self) -> int:
+            """Single breeding events to run. One event touches one scope, not the whole
+            population.
+            """
+            ...
+        @property
+        def replacement(self) -> ReplacementConfig:
+            """Who the children overwrite; omitted, the least fit.
+
+            `Worst` is what makes steady-state self-elitist; `Random` gives that up.
+            """
+            ...
+
+class ReplacementConfig:
+    """Which members of a scope a mating event's children overwrite."""
+
+    class Random(ReplacementConfig):
+        """Children overwrite individuals drawn uniformly from the scope, giving up
+        steady-state's self-elitism.
+        """
+        def __init__(self) -> None:
+            ...
+
+    class Worst(ReplacementConfig):
+        """Children overwrite the least fit of the scope.
+
+        This is what makes steady-state self-elitist.
+        """
+        def __init__(self) -> None:
+            ...
+
+class ScopeConfig:
+    """The slice of the population one breeding event draws from."""
+
+    class Global(ScopeConfig):
+        """Every individual is a candidate. Consumes no randomness."""
+        def __init__(self) -> None:
+            ...
+
+    class RandomSubset(ScopeConfig):
+        """`size` distinct individuals, drawn uniformly without replacement."""
+        def __init__(self, size: int) -> None:
+            ...
+        @property
+        def size(self) -> int:
+            """At least 1 and at most `population_size` — and at least 4 under steady-
+            state, which needs two parents and two distinct individuals for them to
+            replace. Generational has no such floor.
+            """
+            ...
+
+class SelectionConfig:
+    """Parent-selection strategy."""
+
+    class Best(SelectionConfig):
+        """Takes the scope's fittest, in rank order.
+
+        Consumes no randomness — the scope did the drawing.
+        """
+        def __init__(self) -> None:
+            ...
+
+    class Tournament(SelectionConfig):
+        """Draws `tournament_size` members of the scope with replacement and takes the
+        best, once per parent.
+        """
+        def __init__(self, tournament_size: int) -> None:
+            ...
+        @property
+        def tournament_size(self) -> int:
+            """At least 1. May exceed the population — the floor is checked against the
+            scope's `size` instead.
+            """
+            ...
+
+class CrossoverConfig:
+    """Recombination operator."""
+
+    class TwoPoint(CrossoverConfig):
+        """Two cut points, the middle segment exchanged. The only operator that
+        ships.
+        """
+        def __init__(self) -> None:
+            ...
+
+class EdgeEditMutationConfig:
+    """Which mutation an edge-edit genome applies."""
+
+    class RerollGene(EdgeEditMutationConfig):
+        """Redraws one edit operation in the genome."""
+        def __init__(self) -> None:
+            ...
+
+class SdaMutationConfig:
+    """Which mutation an SDA genome applies."""
+
+    class RedrawOne(SdaMutationConfig):
+        """Redraws one element of the automaton — the initial character, a transition's
+        target, or its response.
+        """
+        def __init__(self) -> None:
+            ...
+
+class GenomeConfig:
+    """Genome representation and the dimensions used to build random individuals."""
+
+    class EdgeEdit(GenomeConfig):
+        """A list of edit operations; the graph is what replaying them produces."""
+        def __init__(self, gene_length: int, operation_weights: OperationWeights | None=None, mutation: EdgeEditMutationConfig | None=None) -> None:
+            ...
+        @property
+        def gene_length(self) -> int:
+            """Number of edit operations in the genome."""
+            ...
+        @property
+        def mutation(self) -> EdgeEditMutationConfig | None:
+            """Which mutation the run applies; omitted, the default one."""
+            ...
+        @property
+        def operation_weights(self) -> OperationWeights | None:
+            """Relative weight per edit operation; omitted, every operation weighs
+            1.0.
+            """
+            ...
+
+    class Sda(GenomeConfig):
+        """A self-driving automaton whose output is read as the graph's edges.
+
+        No `num_chars`: the alphabet is `max_edge_multiplicity + 1`, so every
+        character is a legal edge weight.
+        """
+        def __init__(self, num_states: int, max_resp_len: int, init_state: int=0, init_char_mutation_rate: float | None=None, transition_vs_response_rate: float | None=None, mutation: SdaMutationConfig | None=None) -> None:
+            ...
+        @property
+        def init_char_mutation_rate(self) -> float | None:
+            """Chance a mutation redraws the initial character instead of touching the
+            transition table; omitted, the default rate.
+            """
+            ...
+        @property
+        def init_state(self) -> int:
+            """State the automaton starts in. Must be less than `num_states`, or
+            expression panics.
+            """
+            ...
+        @property
+        def max_resp_len(self) -> int:
+            """Longest response string a transition may emit.
+
+            Responses are drawn from `1..=max_resp_len` and are never empty, which is
+            what guarantees the automaton terminates.
+            """
+            ...
+        @property
+        def mutation(self) -> SdaMutationConfig | None:
+            """Which mutation the run applies; omitted, the default one."""
+            ...
+        @property
+        def num_states(self) -> int:
+            """States in the automaton."""
+            ...
+        @property
+        def transition_vs_response_rate(self) -> float | None:
+            """Chance of redrawing a transition's target rather than its response, once
+            the initial character was not chosen.
+            """
+            ...
+
+class FitnessConfig:
+    """Fitness objective and its parameters.
+
+    The epidemic objectives read one simulation differently, so they share a
+    single `SirParams` block.
+    """
+
+    class EpiLength(FitnessConfig):
+        """Timesteps to burn out. Maximized."""
+        def __init__(self, sir: SirParams) -> None:
+            ...
+        @property
+        def sir(self) -> SirParams:
+            """Epidemic sampling parameters, shared by the three epidemic objectives."""
+            ...
+
+    class EpiProfMatch(FitnessConfig):
+        """RMSE against a target profile. Minimized."""
+        def __init__(self, sir: SirParams, target_profile: list[float]) -> None:
+            ...
+        @property
+        def sir(self) -> SirParams:
+            """Epidemic sampling parameters, shared by the three epidemic objectives."""
+            ...
+        @property
+        def target_profile(self) -> list[float]:
+            """The profile the run is scored against, compared verbatim — nothing is
+            prepended to it and nothing is rescaled.
+            """
+            ...
+
+    class EpiSpread(FitnessConfig):
+        """Total ever-infected. Maximized."""
+        def __init__(self, sir: SirParams) -> None:
+            ...
+        @property
+        def sir(self) -> SirParams:
+            """Epidemic sampling parameters, shared by the three epidemic objectives."""
+            ...
+
+    class Python(FitnessConfig):
+        """A Python callable registered before the run, via
+        `GraphEvolver.set_fitness_function`. Whether it is maximized or minimized is
+        declared at registration, not here.
+        """
+        def __init__(self) -> None:
+            ...
+
+    class StructMatch(FitnessConfig):
+        """How closely a graph's structure matches a set of reference graphs.
+
+        Minimized; requires `max_edge_multiplicity = 1`.
+        """
+        def __init__(self, reference_folder: str, degree_bins: int=50, clustering_bins: int=50, spectral_bins: int=50, degree_gamma: float=1.0, clustering_gamma: float=1.0, spectral_gamma: float=1.0, degree_weight: float=1.0, clustering_weight: float=1.0, spectral_weight: float=1.0, density_weight: float=1.0) -> None:
+            ...
+        @property
+        def clustering_bins(self) -> int:
+            """Histogram bins for the clustering statistics. More bins resolve finer
+            differences and need more reference graphs to fill them.
+            """
+            ...
+        @property
+        def clustering_gamma(self) -> float:
+            """RBF bandwidth for the clustering statistics. Must be finite and greater
+            than zero — the kernel divides by it. Too large is the dangerous
+            direction: the kernel collapses to zero for every candidate, the whole
+            population scores about the same, and evolution stalls while appearing to
+            run normally.
+            """
+            ...
+        @property
+        def clustering_weight(self) -> float:
+            """How much the clustering family counts. Finite and non-negative; the three
+            family weights cannot all be zero, which would score every candidate
+            identically.
+            """
+            ...
+        @property
+        def degree_bins(self) -> int:
+            """Histogram bins for the degree statistics. More bins resolve finer
+            differences and need more reference graphs to fill them.
+            """
+            ...
+        @property
+        def degree_gamma(self) -> float:
+            """RBF bandwidth for the degree statistics. Must be finite and greater than
+            zero — the kernel divides by it. Too large is the dangerous direction:
+            the kernel collapses to zero for every candidate, the whole population
+            scores about the same, and evolution stalls while appearing to run
+            normally.
+            """
+            ...
+        @property
+        def degree_weight(self) -> float:
+            """How much the degree family counts. Finite and non-negative; the three
+            family weights cannot all be zero, which would score every candidate
+            identically.
+            """
+            ...
+        @property
+        def density_weight(self) -> float:
+            """How much distance from the reference set's mean density counts. Zero
+            switches the penalty off.
+            """
+            ...
+        @property
+        def reference_folder(self) -> str:
+            """Folder of reference graphs, one edge-list file each.
+
+            Not checked when the config is parsed — validation does no I/O, so a
+            missing or empty folder is reported when the run starts.
+            """
+            ...
+        @property
+        def spectral_bins(self) -> int:
+            """Histogram bins for the spectral statistics. More bins resolve finer
+            differences and need more reference graphs to fill them.
+            """
+            ...
+        @property
+        def spectral_gamma(self) -> float:
+            """RBF bandwidth for the spectral statistics. Must be finite and greater
+            than zero — the kernel divides by it. Too large is the dangerous
+            direction: the kernel collapses to zero for every candidate, the whole
+            population scores about the same, and evolution stalls while appearing to
+            run normally.
+            """
+            ...
+        @property
+        def spectral_weight(self) -> float:
+            """How much the spectral family counts. Finite and non-negative; the three
+            family weights cannot all be zero, which would score every candidate
+            identically.
+            """
+            ...
+
+class SirParams:
+    """Epidemic sampling parameters, shared by the epidemic objectives.
+
+    Nothing is range-checked here; every field is checked when the config is
+    handed to an evolver.
+    """
+    def __init__(self, infection_rate: float, num_epidemics: int, patient_zero: int | None=None, min_epidemic_length: int=3, max_epidemic_retries: int=5) -> None:
+        ...
+    @property
+    def infection_rate(self) -> float:
+        """Per-edge transmission probability per timestep."""
+        ...
+    @property
+    def max_epidemic_retries(self) -> int:
+        """Attempts before keeping whatever came out."""
+        ...
+    @property
+    def min_epidemic_length(self) -> int:
+        """Outbreaks shorter than this are re-rolled; 1 disables the re-roll."""
+        ...
+    @property
+    def num_epidemics(self) -> int:
+        """Outbreaks averaged per evaluation."""
+        ...
+    @property
+    def patient_zero(self) -> int | None:
+        """Pinned patient zero; left unset, a fresh node is drawn per epidemic."""
+        ...
+
+class OperationWeights:
+    """Relative probability of each edge-edit operation.
+
+    Every weight defaults to 1.0, so the operations are equally likely; 0.0
+    disables an operation outright.
+    """
+    def __init__(self, toggle: float=1.0, hop: float=1.0, add: float=1.0, delete: float=1.0, swap: float=1.0, local_toggle: float=1.0, local_add: float=1.0, local_delete: float=1.0, null: float=1.0) -> None:
+        ...
+
+class RunResult:
+    """Everything one run produced.
+
+    Returned by `GraphEvolver.run`. The evolver keeps none of it, so it is
+    reusable across runs and never reports a previous one's numbers.
+    """
+    @property
+    def best_edges(self) -> list[tuple[int, int, int]]:
+        """The best individual's expressed network, as `(u, v, multiplicity)`."""
+        ...
+    @property
+    def best_fitness(self) -> float:
+        """Best of the **final** population, **as-measured** — the units and sign
+        your objective returned. Matches `history`'s last row, which a
+        stochastic objective may have scored worse than an earlier one.
+        """
+        ...
+    @property
+    def best_genome_repr(self) -> str:
+        """The best individual's genome, via `Genome::print`."""
+        ...
+    @property
+    def config_toml(self) -> str:
+        """The TOML document this run's config was parsed from. `save_config`
+        writes it into a folder, so the run can be reproduced.
+        """
+        ...
+    @property
+    def history(self) -> list[GenerationStats]:
+        """The convergence log, one row per logged iteration."""
+        ...
+    @property
+    def num_nodes(self) -> int:
+        """How many nodes that network has, isolated ones included."""
+        ...
+    @property
+    def run_index(self) -> int:
+        """Which replicate this is, `0`-based. With `seed`, the pair that
+        reproduces this exact run.
+        """
+        ...
+    def save_config(self, directory: str) -> None:
+        """Write the run's config TOML into `directory` as `config.toml`.
+
+        Called once per invocation rather than once per replicate: every
+        replicate of one invocation was produced by the same document, and a
+        copy beside each would be the same bytes N times.
+        """
+        ...
+    def save_logs(self, filename: str) -> None:
+        """Write the convergence log to `filename` as CSV.
+
+        Every row carries `seed` and `run_index`, so logs from several runs
+        concatenate into one file and stay separable.
+        """
+        ...
+    def save_results(self, filename: str) -> None:
+        """Write the best individual to `filename`.
+
+        **The file is a loadable edge list**, which GET reads back unedited.
+
+        The config that produced it is not written here — it belongs to the
+        whole invocation rather than to one replicate, so `save_config` writes
+        it once into the folder the replicates share.
+        """
+        ...
+    @property
+    def seed(self) -> int:
+        """The seed `run` was called with."""
+        ...
+
+class GenerationStats:
+    """One row of the convergence log.
+
+    `iteration` counts generations under the generational strategy and mating
+    events under steady-state.
+    """
+    @property
+    def best_fitness(self) -> float:
+        """Best fitness in the population at this iteration."""
+        ...
+    @property
+    def ci_95(self) -> float:
+        """Half-width of the 95% confidence interval on `mean_fitness`, using the
+        **sample** deviation, dividing by `n - 1` — not `std_dev` beside it.
+        Zero for a population of one, never `NaN`.
+        """
+        ...
+    @property
+    def iteration(self) -> int:
+        """Generation number, or mating-event number."""
+        ...
+    @property
+    def mean_fitness(self) -> float:
+        """Population mean fitness at this iteration."""
+        ...
+    @property
+    def std_dev(self) -> float:
+        """**Population** standard deviation, dividing by `n`. Zero for a
+        population of one.
+        """
+        ...