Start Here

Getting Started

Install the Python package, run a small experiment, and identify the main parts of the result. No graph theory or evolutionary-computing background is required.

Before You Begin

Python 3.8 or newer
A supported 64-bit Linux, macOS, or Windows platform

On Windows, in PowerShell: use py in place of python3, skip the activate line entirely, because a stock machine refuses to run it, and write .venv\Scripts\python.exe wherever a command on this page says python or python3. pip becomes .venv\Scripts\python.exe -m pip. That substitution is the whole Windows route; nothing else on this page differs. If you would rather have an activated shell, see PowerShell refuses to run Activate.ps1.

You can confirm the tools are visible with:

python3 --version
python3 -m pip --version

1. Install the Python Package

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install graph-evolution-tool
python -c "import get; print('GET imported')"

The project is named graph-evolution-tool, but Python imports it as get. PyPI provides version 0.9.0 as platform wheels. Pin it with graph-evolution-tool==0.9.0 when an environment must resolve the same release later. Contributors changing Rust source should instead follow the source-build guide.

2. Run a Small Evolution

Save this as first_run.py in your working directory:

import get

config = get.Config(
    population_size=16,
    network_size=12,
    crossover_rate=0.9,
    mutation_rate=0.2,
    evolution=get.EvolutionConfig.Generational(
        num_generations=5,
        elite_count=1,
    ),
    scope=get.ScopeConfig.Global(),
    selection=get.SelectionConfig.Tournament(tournament_size=3),
    genome=get.GenomeConfig.EdgeEdit(gene_length=32),
    fitness=get.FitnessConfig.EpiSpread(
        sir=get.SirParams(infection_rate=0.5, num_epidemics=4)
    ),
)

evolver = get.GraphEvolver.from_config(config)
result = evolver.run(seed=7, n_runs=1)[0]

print("best score:", result.best_fitness)
print("edges:", len(result.best_edges))
print("genome:", result.best_genome_repr)
print("history rows:", len(result.history))

python first_run.py

The exact result is deterministic for this version and seed. You should see one score, an edge count, the winning genome representation, and six history rows: the initial population plus five generations.

3. Read the Result

Result	Meaning
`best_fitness`	The objective value of the winning graph, in the direction you requested.
`best_edges`	`(u, v, multiplicity)` triples for the winning network.
`best_genome_repr`	The winning individual's genome, formatted by its genome implementation.
`history`	The best and population-level scores at each logged iteration.

Save the convergence log, winning graph and genome, and the configuration when you are ready:

result.save_logs("run_log.csv")
result.save_results("best_individual.txt")
result.save_config(".")                     # writes config.toml

What to Change First

Increase num_generations after the small run works.
Use n_runs greater than one for replicates.
Choose a different built-in objective or write a Python objective.
Move the settings into a TOML file when you want an experiment document to archive and compare.

If It Does Not Run

Go to Troubleshooting for import, compiler, configuration, output-path, and stalled-evolution problems. If the run works and you want the theory, continue with Concepts & Vocabulary.