Skip to content
fhamonicPublic

About

Graph-based Ecological Connectivity Optimization Tool

Topics

Resources

Contributing

Stars

10 stars

Watchers

1 watching

Forks

Repository files navigation

GECOT

GECOT, the Graph-based Ecological Connectivity Optimization Tool, is an open-source C++ tool designed to tackle systematic conservation (or restoration) planning problems. Given a graph representation of the landscape for each target species, a list of actions for improving the graphs elements and a budget, GECOT allows to select a group of actions whose cost is below the budget and whose impacts on the Landscapes maximizes the ecological connectivity, measured with the Probability of Connectivity indicator (PC).

Generic badge Generic badge Generic badge Generic badge Documentation

Installation

For Windows, download and run the last released installer.

For Linux, download and extract the precompiled binaries of the last release.

Otherwise, here is a Docker container for building and testing GECOT.

Documentation

📖 fhamonic.github.io/gecot — the instance files, the commands, the algorithms and their mathematical formulations. The sources are under docs/; preview them locally with pip install zensical && zensical serve.

Usage

$ gecot --help
GECOT — Graph-based Ecological Connectivity Optimization Tool
Version: 2.0

Usage:
  gecot --help
  gecot --version
  gecot optimize --help
  gecot optimize <algorithm> <instance> <budget> [<parameters> ...]
  gecot bound --help
  gecot bound <method> <instance> <budget> [<parameters> ...]

Commands:
  optimize    Select options within a budget to maximize the score
  bound       Bound the best score of the options within a budget

gecot optimize selects the options to buy within the budget:

$ gecot optimize --help
GECOT — Graph-based Ecological Connectivity Optimization Tool
Version: 2.0

Usage:
  gecot optimize --help
  gecot optimize --list-algorithms
  gecot optimize <algorithm> --list-params
  gecot optimize <algorithm> <instance> <budget> [<parameters> ...]


POSITIONALS:
  algorithm TEXT              Algorithm to use
  instance TEXT               Instance JSON file
  budget BUDGET               Budget value, or name=value,... for options of several costs

OPTIONS:
  -h,     --help              Display this help message
  -A,     --list-algorithms   List the available algorithms
  -P,     --list-params       List the parameters of the chosen algorithm
  -a,     --algorithm TEXT    Algorithm to use
  -i,     --instance TEXT     Instance JSON file
  -B,     --budget BUDGET     Budget value, or name=value,... for options of several costs
  -o,     --output-json TEXT  Output solution data in JSON file
          --output-csv TEXT   Output solution value in CSV file
          --reformulation TEXT:{trivial,path_lp} [trivial]
                              Instance given to the algorithm, trivial: without the options
                              over the budget, and those of cost 0, bought unless a conflict
                              set makes them a choice; path_lp: also without the options that
                              the path relaxation proves to be in no better solution than its
                              own
          --reformulation-params TEXT
                              Parameters of the path_lp of --reformulation path_lp, as
                              "time-limit=60 pricing=enumerate"; its MIP start is greedy's
                              solution by default
          --no-merging        For comparison: keeps apart the vertices that arcs of probability
                              1 link, merged in the instance given to the algorithm
  -v,     --verbose [0]       Log the algorithms' details, -vv everything with the solver's own
                              log on stdout
  -q,     --quiet             Silence all logging except errors
          --max-threads UINT:POSITIVE
                              Limits the number of threads of GECOT's own computations, not
                              those of the solver

gecot bound computes an upper bound on the scores gecot optimize can reach within the budget, the options of cost 0 being always bought unless a conflict set makes them a choice, which certifies how far a solution is from the optimum:

$ gecot bound --help
GECOT — Graph-based Ecological Connectivity Optimization Tool
Version: 2.0

Usage:
  gecot bound --help
  gecot bound --list-methods
  gecot bound <method> --list-params
  gecot bound <method> <instance> <budget> [<parameters> ...]


POSITIONALS:
  method TEXT                 Bound method to use
  instance TEXT               Instance JSON file
  budget BUDGET               Budget value, or name=value,... for options of several costs

OPTIONS:
  -h,     --help              Display this help message
  -M,     --list-methods      List the available bound methods
  -P,     --list-params       List the parameters of the chosen method
          --method TEXT       Bound method to use
  -i,     --instance TEXT     Instance JSON file
  -B,     --budget BUDGET     Budget value, or name=value,... for options of several costs
  -o,     --output-json TEXT  Output bound data in JSON file
  -v,     --verbose [0]       Log the methods' details, -vv everything with the solver's own
                              log on stdout
  -q,     --quiet             Silence all logging except errors
          --max-threads UINT:POSITIVE
                              Limits the number of threads of GECOT's own computations, not
                              those of the solver

gecot optimize --list-algorithms and gecot bound --list-methods describe the algorithms and the bound methods, and --list-params their parameters. The gecot_optimize <algorithm> ... command of former releases is now gecot optimize <algorithm> .... Of its algorithms, prep_mip is now flow_mip and mip is flow_mip --preprocessing none; static_incr and greedy_incr are static and greedy, static_decr and greedy_decr are static --decremental and greedy --decremental.

The result is printed on stdout, unless -o or --output-csv writes it to a file. The log goes to stderr, each line after the seconds since the start: the steps of the run, then a table of the algorithm's progress, with a row when a value changes, at most every 5 s and at least every minute, and a last row with the state it ended in. Its gain is the best solution's over the initial score, max gain the best possible gain, proven, and guaranteed the share of this best possible gain that the solution is proven to reach. The rows of tree_lp and path_lp are their rounds, with the fractional gain of their master, the gain of a plan that buys parts of options; multiflow_benders first shows the rounds of its cuts on the relaxation, whose value is a max gain, with a fractional gain and the violation of its cuts. Ctrl-C stops the algorithm and keeps its best result so far, with the status interrupted; a second Ctrl-C quits at once. A MIP solver notices it only when it next reports its progress: within seconds with Gurobi once it has begun to report, which can take tens of seconds on a large model, up to about 15 s apart with HiGHS on a large model, never with CBC, which reports none. The column generations of tree_lp and path_lp stop in their pricing, greedy after its current step, and static runs to the end.

Citation

Please cite 'GECOT' when using it in publications using:

Hamonic, F., Vaxès, Y., Couëtoux, B., & Albert, C. H. (2025). GECOT: Graph-based ecological connectivity optimization tool. Methods in Ecology and Evolution, 00, 1–9. https://doi.org/10.1111/2041-210X.70055

Additionally, releases are automatically published to Zenodo (https://doi.org/10.5281/zenodo.15295914)

Acknowledgments

This work has been funded by Region Sud and Natural Solutions (PhD thesis of François Hamonic), and by the ERC project SCALED, grant n°949812 (postdoctoral position).

About

Graph-based Ecological Connectivity Optimization Tool

Topics

Resources

Contributing

Stars

10 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages