[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is a grid matching & conversion tool primarily developed
for the comparison of power grids.
# Installation
[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is available on [PyPI](https://pypi.org/) and can be
installed into your Python environment via `pip`:
```bash
pip install dlr.esy.grid.match
```
# Command-line interface
[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) provides a command-line interface (see
[`dlr.esy.grid.match.cli`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match/cli.html) for more details):
```console
$ dlr.esy.grid.match --help
usage: dlr.esy.grid.match [-h] {compare,example} ...
...
Command-line interface for grid comparisons.
...
positional arguments:
{compare,example}
compare Compares two powergrids. `a` and `b` are expected to be
directories, each containing the files `bus.csv` and
`line.csv`.
example Creates an example datasets.
...
```
## Usage
The command `compare` adds the columns `center` and `map` to the grids $a$ and
$b$. The column `center` contains the index of the center of the cluster each
node belongs to and the column `map` the index of the center of the
corresponding cluster in the other grid. See the methodology section for
details. The subcommand `grids` plots the two grids together and the
subcommand `plot` shows or saves the plots.
The subcommand `example` can be used to create example datasets and write them
into a directory, like the `simple` dataset:
```console
$ dlr.esy.grid.match example simple example/simple
$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b grid plot --save=figures/grids.svg
```
The subcommand `cluster` plots the grids separately highlighting the convex
hulls of each cluster (in orange for the hulls in the plotted grid and in grey
for the ones in the other grid). The centers and the intercluster lines are
plotted in red and the intracluster lines and the rest of the nodes are
plotted in orange.
```console
$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b cluster plot --save=figures/cluster.svg
```
The subcommand `join` produces a third grid with the nodes in gird $a$ which
are in the interior of a region and the nodes in grid $b$ which are outside of
a region. The information about the regions needs to be in a column called
`join` in each grid (0 meaning inside the region and 1 meaning outside).
If the column `join` is missing, it can be added to each grid with the
subcommand `max_res`, as described in the methodology section.
```console
$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b max_res join grid plot --save=figures/join.svg
```
## Input and output
[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) supports reading and writing grid data from CSV files. Grid
data may also be converted to geojson data.
[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) requires `bus` data to contain at least the fields `name`, `x`
and `y`, while `line` data is required to contain at least the fields `name`,
`bus0` and `bus1`.
Input field names can be renamed as in the following example, which reads grid
data from a non-conformative example in the directory `example/nonconformative`
and stores the resulting grid in `example/conformative`:
```console
$ dlr.esy.grid.match example nonconformative example/nonconformative
$ dlr.esy.grid.match compare --a=example/nonconformative/a --a_bus_fields=bus:name --a_line_fields=line:name --b=example/nonconformative/b --b_bus_fields=bus:name --b_line_fields=line:name csv example/conformative
```
The command `geojson` produces a geojson output, which can be used to visualize
the grids with the clusters, for instance by importing it to
[https://geojson.io/](https://geojson.io/).
```console
$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b geojson
{"type": "FeatureCollection", ...}
```
# Methodology
## Comparison methodology
Given two grids $a$ and $b$ with geolocated nodes, clusters of nodes in
each grid are produced and each cluster in $a$ is uniquely identified to
a cluster in $b$. The method has the following steps:
1. For each node $n_a$ in $a$, define $f(n_a)$ to be its closest node in $b$
(using the Euclidean distance) and, for each node $n_b$ in $b$, define
$g(n_b)$ to be its closest node in $a$.
2. Each node $n_a$ in $a$ such that $g(f(n_a))=n_a$ is chosen as center
of a cluster in $a$ and each node $n_b$ in $b$ such that
$f(g(n_b))=n_b$ is chosen as center of a cluster in $b$. Notice
that, by construction, each grid has the same number of clusters and
there is a one to one correspondence between them. Namely, the center $n_a$
is associated to the center $n_b = f(n_a)$ and the center $n_b$ is
associated to $n_a = g(n_b)$.
3. Each node in $a$ not being a center of any cluster is assigned
to a cluster using the shortest path (using Euclidean distance) to a
center. The same is done for $b$.
The output associates to each node the center of its cluster and also the
corresponding center in the other grid. This can be used to compare and
transfer the data associated to the nodes in both grids. It can also be used to
create a third grid with the highest spatial resolution of both, as explained
in the next section.
## Joining methodology
Given two grids $a$ and $b$ in which all nodes are geolocated and assigned to
one of two regions $\Gamma$ or $\Omega$, a new grid is produced having the
nodes of $a$ which belong to $\Gamma$ and the nodes of $b$ which belong
to $\Omega$. The lines of the joined grid are the ones in the three following
groups:
- Lines in $a$ connecting two nodes belonging to $\Gamma$;
- Lines in $b$ connecting two nodes belonging to $\Omega$; and
- for each line in $a$ connecting a node $n_a$ in $\Gamma$ to a node $m_a$ in
$\Omega$ a line connecting $n_a$ to the closest
node (using Euclidean distance) in $b$ which belongs to $\Omega$.
To get the joined grid with the maximal resolution, the output of the comparison
methodology is used, where a node in $a$ is assigned to $\Gamma$ if it belongs
to a cluster with more or equal number of elements than its corresponding
cluster in $b$.
# Design, Development & Contributing
Design and development notes are available in [`dlr.esy.grid.match.test`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match/test.html).
We would be happy to accept contributions via merge requests, but due to
corporate policy we can only accept contributions if you have send us the signed
[contributor license agreement](https://gitlab.com/dlr-ve/esy/dlr.esy.grid.match/-/blob/main/CLA.md).
# License
[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is licensed under the [MIT](https://mit-license.org/)
license.
# Contact
Please use the projects issue tracker to get in touch.
# Team
[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is developed cooperatively by the
[DLR](https://www.dlr.de/EN/Home/home_node.html) Institute of
[Networked Energy Systems](https://www.dlr.de/ve/en/desktopdefault.aspx/tabid-12472/21440_read-49440/)
in the departement for
[Energy Systems Analysis (ESY)](https://www.dlr.de/ve/en/desktopdefault.aspx/tabid-12471/21741_read-49802/) and
by the
[Institute of Energy and Climate Research](https://www.fz-juelich.de/en/iek) -
[Techno-economic System Analysis (IEK-3)](https://www.fz-juelich.de/en/iek/iek-3)
of the [Forschungszentrum Jülich](https://www.fz-juelich.de/en).
# Footnotes
Test console examples.
```python
>>> import dlr.esy.grid.match.test
>>> dlr.esy.grid.match.test.doctest_console(__doc__)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "dlr-esy-grid-match",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "OSM, OpenStreetMap, power grid, graph, energy modelling",
"author": null,
"author_email": "Oriol Ravent\u00f3s Morera <oriol.raventosmorera@dlr.de>, Ontje L\u00fcnsdorf <ontje.luensdorf@dlr.de>, Theresa Kl\u00fctz <t.kluetz@fz-juelich.de>, Abhilash Bandam <a.bandam@fz-juelich.de>",
"download_url": "https://files.pythonhosted.org/packages/b1/82/f25c0203849f101059deda8d38e2c42e9c6c32bda7888447371325e4ad6d/dlr_esy_grid_match-0.1.tar.gz",
"platform": null,
"description": "\n\n\n\n[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is a grid matching & conversion tool primarily developed\nfor the comparison of power grids.\n\n# Installation\n\n[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is available on [PyPI](https://pypi.org/) and can be\ninstalled into your Python environment via `pip`:\n\n```bash\npip install dlr.esy.grid.match\n```\n\n# Command-line interface\n\n[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) provides a command-line interface (see\n[`dlr.esy.grid.match.cli`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match/cli.html) for more details):\n\n```console\n$ dlr.esy.grid.match --help\nusage: dlr.esy.grid.match [-h] {compare,example} ...\n...\nCommand-line interface for grid comparisons.\n...\npositional arguments:\n {compare,example}\n compare Compares two powergrids. `a` and `b` are expected to be\n directories, each containing the files `bus.csv` and\n `line.csv`.\n example Creates an example datasets.\n...\n\n```\n\n## Usage\n\nThe command `compare` adds the columns `center` and `map` to the grids $a$ and\n$b$. The column `center` contains the index of the center of the cluster each\nnode belongs to and the column `map` the index of the center of the\ncorresponding cluster in the other grid. See the methodology section for \ndetails. The subcommand `grids` plots the two grids together and the \nsubcommand `plot` shows or saves the plots.\n\nThe subcommand `example` can be used to create example datasets and write them\ninto a directory, like the `simple` dataset:\n\n```console\n$ dlr.esy.grid.match example simple example/simple\n$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b grid plot --save=figures/grids.svg\n```\n\n\n\nThe subcommand `cluster` plots the grids separately highlighting the convex\nhulls of each cluster (in orange for the hulls in the plotted grid and in grey\nfor the ones in the other grid). The centers and the intercluster lines are\nplotted in red and the intracluster lines and the rest of the nodes are\nplotted in orange.\n\n```console\n$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b cluster plot --save=figures/cluster.svg\n```\n\n\n\nThe subcommand `join` produces a third grid with the nodes in gird $a$ which\nare in the interior of a region and the nodes in grid $b$ which are outside of\na region. The information about the regions needs to be in a column called\n`join` in each grid (0 meaning inside the region and 1 meaning outside).\nIf the column `join` is missing, it can be added to each grid with the\nsubcommand `max_res`, as described in the methodology section.\n\n```console\n$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b max_res join grid plot --save=figures/join.svg\n```\n\n\n\n## Input and output\n\n[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) supports reading and writing grid data from CSV files. Grid\ndata may also be converted to geojson data.\n\n[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) requires `bus` data to contain at least the fields `name`, `x`\nand `y`, while `line` data is required to contain at least the fields `name`,\n`bus0` and `bus1`.\n\nInput field names can be renamed as in the following example, which reads grid\ndata from a non-conformative example in the directory `example/nonconformative`\nand stores the resulting grid in `example/conformative`:\n\n```console\n$ dlr.esy.grid.match example nonconformative example/nonconformative\n$ dlr.esy.grid.match compare --a=example/nonconformative/a --a_bus_fields=bus:name --a_line_fields=line:name --b=example/nonconformative/b --b_bus_fields=bus:name --b_line_fields=line:name csv example/conformative\n```\n\nThe command `geojson` produces a geojson output, which can be used to visualize\nthe grids with the clusters, for instance by importing it to\n[https://geojson.io/](https://geojson.io/).\n\n```console\n$ dlr.esy.grid.match compare --a=example/simple/a --b=example/simple/b geojson\n{\"type\": \"FeatureCollection\", ...}\n```\n\n# Methodology\n\n## Comparison methodology\n\nGiven two grids $a$ and $b$ with geolocated nodes, clusters of nodes in\neach grid are produced and each cluster in $a$ is uniquely identified to\na cluster in $b$. The method has the following steps:\n\n1. For each node $n_a$ in $a$, define $f(n_a)$ to be its closest node in $b$\n (using the Euclidean distance) and, for each node $n_b$ in $b$, define \n $g(n_b)$ to be its closest node in $a$.\n\n2. Each node $n_a$ in $a$ such that $g(f(n_a))=n_a$ is chosen as center\n of a cluster in $a$ and each node $n_b$ in $b$ such that\n $f(g(n_b))=n_b$ is chosen as center of a cluster in $b$. Notice\n that, by construction, each grid has the same number of clusters and\n there is a one to one correspondence between them. Namely, the center $n_a$\n is associated to the center $n_b = f(n_a)$ and the center $n_b$ is \n associated to $n_a = g(n_b)$.\n\n3. Each node in $a$ not being a center of any cluster is assigned\n to a cluster using the shortest path (using Euclidean distance) to a\n center. The same is done for $b$.\n\nThe output associates to each node the center of its cluster and also the\ncorresponding center in the other grid. This can be used to compare and\ntransfer the data associated to the nodes in both grids. It can also be used to\ncreate a third grid with the highest spatial resolution of both, as explained\nin the next section.\n\n## Joining methodology\n\nGiven two grids $a$ and $b$ in which all nodes are geolocated and assigned to\none of two regions $\\Gamma$ or $\\Omega$, a new grid is produced having the\nnodes of $a$ which belong to $\\Gamma$ and the nodes of $b$ which belong\nto $\\Omega$. The lines of the joined grid are the ones in the three following\ngroups:\n\n- Lines in $a$ connecting two nodes belonging to $\\Gamma$;\n\n- Lines in $b$ connecting two nodes belonging to $\\Omega$; and\n\n- for each line in $a$ connecting a node $n_a$ in $\\Gamma$ to a node $m_a$ in\n$\\Omega$ a line connecting $n_a$ to the closest \nnode (using Euclidean distance) in $b$ which belongs to $\\Omega$.\n\nTo get the joined grid with the maximal resolution, the output of the comparison\nmethodology is used, where a node in $a$ is assigned to $\\Gamma$ if it belongs\nto a cluster with more or equal number of elements than its corresponding\ncluster in $b$.\n\n# Design, Development & Contributing\n\nDesign and development notes are available in [`dlr.esy.grid.match.test`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match/test.html).\n\nWe would be happy to accept contributions via merge requests, but due to\ncorporate policy we can only accept contributions if you have send us the signed\n[contributor license agreement](https://gitlab.com/dlr-ve/esy/dlr.esy.grid.match/-/blob/main/CLA.md).\n\n# License\n\n[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is licensed under the [MIT](https://mit-license.org/)\nlicense.\n\n# Contact\n\nPlease use the projects issue tracker to get in touch.\n\n# Team\n\n[`dlr.esy.grid.match`](https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match/dlr/esy/grid/match.html) is developed cooperatively by the\n[DLR](https://www.dlr.de/EN/Home/home_node.html) Institute of\n[Networked Energy Systems](https://www.dlr.de/ve/en/desktopdefault.aspx/tabid-12472/21440_read-49440/)\nin the departement for\n[Energy Systems Analysis (ESY)](https://www.dlr.de/ve/en/desktopdefault.aspx/tabid-12471/21741_read-49802/) and\nby the\n[Institute of Energy and Climate Research](https://www.fz-juelich.de/en/iek) -\n[Techno-economic System Analysis (IEK-3)](https://www.fz-juelich.de/en/iek/iek-3)\nof the [Forschungszentrum J\u00fclich](https://www.fz-juelich.de/en).\n\n# Footnotes\n\nTest console examples.\n\n```python\n>>> import dlr.esy.grid.match.test\n>>> dlr.esy.grid.match.test.doctest_console(__doc__)\n\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "grid matching & conversion tool",
"version": "0.1",
"project_urls": {
"documentation": "https://dlr-ve.gitlab.io/esy/dlr.esy.grid.match",
"homepage": "https://gitlab.com/dlr-ve/esy/dlr.esy.grid.match",
"tracker": "https://gitlab.com/dlr-ve/esy/dlr.esy.grid.match/issues"
},
"split_keywords": [
"osm",
" openstreetmap",
" power grid",
" graph",
" energy modelling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4624f147385296453b8dda11c48c83e6de213e0f1ceea68d7021e86b9c55b090",
"md5": "eee0d6782212c7f4ed90c4e6d662f91f",
"sha256": "ab771f730b6a274e387a0d29ab79895273038ae698cf8fc60064a6dcc5f1ca86"
},
"downloads": -1,
"filename": "dlr_esy_grid_match-0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eee0d6782212c7f4ed90c4e6d662f91f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 26456,
"upload_time": "2024-06-25T08:06:12",
"upload_time_iso_8601": "2024-06-25T08:06:12.147455Z",
"url": "https://files.pythonhosted.org/packages/46/24/f147385296453b8dda11c48c83e6de213e0f1ceea68d7021e86b9c55b090/dlr_esy_grid_match-0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b182f25c0203849f101059deda8d38e2c42e9c6c32bda7888447371325e4ad6d",
"md5": "f9531bd630f9cf047827a8d08b369920",
"sha256": "cb9968b9e5bedb38fae0a8aa4ae5f03224e2fb0e636715ae010b6ff0e01ac133"
},
"downloads": -1,
"filename": "dlr_esy_grid_match-0.1.tar.gz",
"has_sig": false,
"md5_digest": "f9531bd630f9cf047827a8d08b369920",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24249,
"upload_time": "2024-06-25T08:06:00",
"upload_time_iso_8601": "2024-06-25T08:06:00.455862Z",
"url": "https://files.pythonhosted.org/packages/b1/82/f25c0203849f101059deda8d38e2c42e9c6c32bda7888447371325e4ad6d/dlr_esy_grid_match-0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-25 08:06:00",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "dlr-ve",
"gitlab_project": "esy",
"lcname": "dlr-esy-grid-match"
}
JSON