GeNet provides tools to represent and work with a multi-modal transport network with public transport (PT) services. It is based on MATSim's representation of such networks.
The goal of GeNet is to:
- Provide a formalised in-memory data structure for representing a multi-modal network with a PT service
- Enable using the data structure for tasks such as generating auxiliary MATSim files e.g. Road Pricing
- Simplify the process of modifying a network and provide a simple change log to track the differences between the input and output networks.
- Provide validation methods to check for simple errors such as: whether a
Routehas more than oneStopor that the underlying graph doesn't have any dead-ends or sources (a place which you can leave but cannot get back to).
The underlying
network available to PT services (roads, railways, but also ferry/flight connections) uses a networkx.MultiDiGraph
with additional methods for 'links' which are unique in genet.Network (networkx.MultiDiGraph accepts multiple
edges between the same from and to node pair; referring to an edge in networkx.MultiDiGraph and genet.Network
has the same effects, i.e. the result is a dictionary indexed by the multi edge index). The PT services are
represented through the genet.Schedule class which relies on other genet
classes: the Schedule relies on a list of genet.Service's, which in turn consists of a list of genet.Route's.
Each Route class object has an attribute stops which consists of genet.Stops objects. The Stops carry spatial
information for the PT stop.
GeNet CLI supports a number of different usage scenarios. For these you can use docker, which will save you the work of installing GeNet locally:
Docker is the recommended way to use GeNet if you do not plan to make any code changes.
docker build -t "cml-genet" .
docker run cml-genet genet --help
to show the list of available commands, and e.g.
docker run cml-genet genet simplify-network --help
to show description of the command and parameters:
Usage: genet simplify-network [OPTIONS]
Simplify a MATSim network by removing intermediate links from paths
Options:
-n, --network PATH Location of the input network.xml file
[required]
-s, --schedule PATH Location of the input schedule.xml file
-v, --vehicles PATH Location of the input vehicles.xml file
-p, --projection TEXT The projection network is in, eg.
"epsg:27700" [required]
-pp, --processes INTEGER Number of parallel processes to split
process across
-vsc, --vehicle_scalings TEXT Comma delimited list of scales for vehicles
-od, --output_dir DIRECTORY Output directory [required]
-fc, --force_strongly_connected_graph
If True, checks for disconnected subgraphs
for modes `walk`, `bike` and `car`. If there
are more than one strongly connected
subgraph, genet connects them with links at
closest points in the graph. The links used
to connect are weighted at 20% of
surrounding freespeed and capacity values.
--help Show this message and exit.
Note, you will reference data outside the docker container as inputs, the docker command will need the path to data mounted and be referenced according to the alias given, e.g.
docker run -v /local/path/:/mnt/ cml-genet genet simplify-network --network /mnt/network.xml [...]
If the input network file lives at /local/path/network.xml.
Say you write a script /local/path/my_genet_scripts/script.py and you want to run it inside a docker container.
You will need to mount the local path to the container for the script to be found and use the generic python
as part of your command:
docker run -v /local/path/:/mnt/ cml-genet python /mnt/my_genet_scripts/script.py
Note, if you reference data inside your script, or pass them as arguments to the script, they need to reference the
aliased path inside the container, here: /mnt/, rather than the path /local/path/.
You can in your base installation of python or a virtual environment. You can use GeNet's CLI to run pre-baked modifications or checks on networks. You can also write your own python scripts, importing genet as a package, use IPython shell or Jupyter Notebook to load up a network, inspect or change it and save it out to file. Check out the wiki pages and example jupyter notebooks for usage examples.
Note: if you plan only to use GeNet rather than make code changes to it, you can avoid having to perform any local installation by using GeNet's Docker image. If you are going to make code changes or use GeNet's CLI locally, follow the steps below:
GeNet uses some Python libraries that rely on underlying native libraries for things like geospatial calculations and linear programming solvers. Before you install GeNet's Python dependencies, you must first install these native libraries.
Note: The default CBC solver is pre-installed inside GeNet's Docker image, which can save you some installation effort
To use methods which snap public transit to the graph, GeNet uses a mathematical solver. If you won't be using such functionality, you do not need to install this solver. Methods default to CBC, an open source solver. Another good open source choice is GLPK. The solver you use needs to support MILP - mixed integer linear programming.
The commands for installing the necessary native libraries vary according to the operating system you are using, for example:
| OS | Commands |
|---|---|
| Mac OS | brew install boost brew install spatialindex brew install gdal --HEAD brew install gdal brew tap coin-or-tools/coinor brew install coin-or-tools/coinor/cbc brew install cbc |
| Ubuntu | sudo apt install libspatialindex-dev sudo apt install libgdal-dev sudo apt install coinor-cbc |
(Use equivalent linux or Windows package management as appropriate for your environment)
brew install python3.11
brew install virtualenv
Create and activate a Python virtual environment
virtualenv -p python3.11 venv
source venv/bin/activate
Finally, install GeNet's Python dependencies
pip install -e .
After installation, you should be able to successfully run the help command to see all possible commands:
genet --help
To inspect a specific command, run e.g.:
genet simplify-network --help
Please follow kepler's installation instructions to be able to use the visualisation methods. To see the maps in a jupyter notebook, make sure you enable widgets.
jupyter nbextension enable --py widgetsnbextension
We welcome community contributions to GeNet; please see our guide to contributing and our community code of conduct. If you are making changes to the codebase, you should use the tools described below to verify that the code still works. All of the following commands assume you are in the project's root directory.
To run unit tests within genet python environment (including testing example notebooks):
pytest
and within a docker container:
docker run cml-genet pytest -vv
In either case, for shorter test runtimes, append 'tests/' to limit to the unit tests and ignore notebook tests.
To generate an HTML coverage report at reports/coverage/index.html:
pytest --cov-report=html
Coverage will also be tracked in pull requests.
Run `pre-commit install` to install pre-commit, which will lint and format your code whenever you commit staged changes.