# GRBlogtools
[](https://pypi.python.org/pypi/grblogtools)
[](https://github.com/Gurobi/grblogtools/blob/master/LICENSE)
[](https://github.com/Gurobi/grblogtools/actions/workflows/python-tox.yml)
Extract information from Gurobi log files and generate [pandas DataFrames](https://pandas.pydata.org/) or Excel worksheets for further processing. Also includes a wrapper for out-of-the-box interactive visualizations using the plotting library [Plotly](https://plotly.com/python/).
# Installation
```
python -m pip install grblogtools
```
It is recommended to prepend the `pip install` command with `python -m` to ensure that the package is installed using the correct Python version currently active in your environment.
See [CHANGELOG](https://github.com/Gurobi/grblogtools/blob/master/CHANGELOG.md) for added, removed or fixed functionality.
# Usage
First, you need a set of Gurobi log files to compare, e.g.,
- results from several model instances
- comparisons of different parameter settings
- performance variability experiments involving multiple random seed runs
- ...
You may also use the provided [grblogtools.ipynb notebook](https://github.com/Gurobi/grblogtools/blob/master/grblogtools.ipynb) with the [example data set](https://github.com/Gurobi/grblogtools/tree/master/data) to get started.
Additionally, there is a [Gurobi TechTalk demonstrating how to use grblogtools (YouTube)](https://youtu.be/wbg4Zr_A1s8):
[](https://youtu.be/wbg4Zr_A1s8)
## Pandas/Plotly
1. parse log files:
```Python
import grblogtools as glt
results = glt.parse(["run1/*.log", "run2/*.log"])
summary = results.summary()
nodelog_progress = results.progress("nodelog")
```
Depending on your requirements, you may need to filter or modify the resulting DataFrames.
2. draw interactive charts, preferably in a [Jupyter Notebook](https://jupyter.org/):
- final results from the individual runs:
```Python
glt.plot(summary, type="box")
```
- progress charts for the individual runs:
```Python
glt.plot(nodelog_progress, y="Gap", color="Log", type="line")
```
- progress of the norel heuristic (note, the time recorded here is since the start of norel, and does not include presolve + read time):
```Python
glt.plot(results.progress("norel"), x="Time", y="Incumbent", color="Log", type="line")
```
These are just examples using the [Plotly Python library](https://plotly.com/python/) - of course, any other plotting library of your choice can be used to work with these DataFrames.
## Excel
Convert your log files to Excel worksheets right on the command-line:
```
python -m grblogtools myrun.xlsx data/*.log
```
List all available options and how to use the command-line tool:
```
python -m grblogtools --help
```
## Rename log files
The command line tool can also rename log files according to the parameters set and model solved in a given run. This is useful if your log files do not have a consistent naming scheme, or if multiple runs are logged per file and you want to extract the individual runs.
For example:
```
python -m grblogtools --write-to-dir nicenames summary.xlsx tests/assets/combined/*.log
```
separates logs for individual runs in the input files and writes copies to the 'nicenames' folder with a consistent naming scheme:
```
> ls nicenames
912-MIPFocus1-Presolve1-TimeLimit600-glass4-0.log
912-MIPFocus1-Presolve1-TimeLimit600-glass4-1.log
912-MIPFocus1-Presolve1-TimeLimit600-glass4-2.log
912-MIPFocus2-Presolve1-TimeLimit600-glass4-0.log
912-MIPFocus2-Presolve1-TimeLimit600-glass4-1.log
912-MIPFocus2-Presolve1-TimeLimit600-glass4-2.log
912-Presolve1-TimeLimit600-glass4-0.log
912-Presolve1-TimeLimit600-glass4-1.log
912-Presolve1-TimeLimit600-glass4-2.log
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Gurobi/grblogtools",
"name": "grblogtools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Gurobi Optimization, LLC",
"author_email": "support@gurobi.com",
"download_url": "https://files.pythonhosted.org/packages/0d/2e/0a318eea59f9ab6e452ebe19937b5d5e644bba7c5b697f12dd5b6adcc024/grblogtools-2.2.0.tar.gz",
"platform": "any",
"description": "# GRBlogtools\n\n[](https://pypi.python.org/pypi/grblogtools)\n[](https://github.com/Gurobi/grblogtools/blob/master/LICENSE)\n[](https://github.com/Gurobi/grblogtools/actions/workflows/python-tox.yml)\n\nExtract information from Gurobi log files and generate [pandas DataFrames](https://pandas.pydata.org/) or Excel worksheets for further processing. Also includes a wrapper for out-of-the-box interactive visualizations using the plotting library [Plotly](https://plotly.com/python/).\n\n\n\n# Installation\n\n```\npython -m pip install grblogtools\n```\n\nIt is recommended to prepend the `pip install` command with `python -m` to ensure that the package is installed using the correct Python version currently active in your environment.\n\nSee [CHANGELOG](https://github.com/Gurobi/grblogtools/blob/master/CHANGELOG.md) for added, removed or fixed functionality.\n\n# Usage\n\nFirst, you need a set of Gurobi log files to compare, e.g.,\n - results from several model instances\n - comparisons of different parameter settings\n - performance variability experiments involving multiple random seed runs\n - ...\n\nYou may also use the provided [grblogtools.ipynb notebook](https://github.com/Gurobi/grblogtools/blob/master/grblogtools.ipynb) with the [example data set](https://github.com/Gurobi/grblogtools/tree/master/data) to get started.\nAdditionally, there is a [Gurobi TechTalk demonstrating how to use grblogtools (YouTube)](https://youtu.be/wbg4Zr_A1s8):\n\n[](https://youtu.be/wbg4Zr_A1s8)\n\n## Pandas/Plotly\n1. parse log files:\n ```Python\n import grblogtools as glt\n\n results = glt.parse([\"run1/*.log\", \"run2/*.log\"])\n summary = results.summary()\n nodelog_progress = results.progress(\"nodelog\")\n ```\n Depending on your requirements, you may need to filter or modify the resulting DataFrames.\n\n2. draw interactive charts, preferably in a [Jupyter Notebook](https://jupyter.org/):\n\n - final results from the individual runs:\n ```Python\n glt.plot(summary, type=\"box\")\n ```\n\n - progress charts for the individual runs:\n ```Python\n glt.plot(nodelog_progress, y=\"Gap\", color=\"Log\", type=\"line\")\n ```\n\n - progress of the norel heuristic (note, the time recorded here is since the start of norel, and does not include presolve + read time):\n ```Python\n glt.plot(results.progress(\"norel\"), x=\"Time\", y=\"Incumbent\", color=\"Log\", type=\"line\")\n ```\n\n These are just examples using the [Plotly Python library](https://plotly.com/python/) - of course, any other plotting library of your choice can be used to work with these DataFrames.\n\n## Excel\nConvert your log files to Excel worksheets right on the command-line:\n\n```\npython -m grblogtools myrun.xlsx data/*.log\n```\n\nList all available options and how to use the command-line tool:\n\n```\npython -m grblogtools --help\n```\n\n## Rename log files\nThe command line tool can also rename log files according to the parameters set and model solved in a given run. This is useful if your log files do not have a consistent naming scheme, or if multiple runs are logged per file and you want to extract the individual runs.\n\nFor example:\n\n```\npython -m grblogtools --write-to-dir nicenames summary.xlsx tests/assets/combined/*.log\n```\n\nseparates logs for individual runs in the input files and writes copies to the 'nicenames' folder with a consistent naming scheme:\n\n```\n> ls nicenames\n912-MIPFocus1-Presolve1-TimeLimit600-glass4-0.log\n912-MIPFocus1-Presolve1-TimeLimit600-glass4-1.log\n912-MIPFocus1-Presolve1-TimeLimit600-glass4-2.log\n912-MIPFocus2-Presolve1-TimeLimit600-glass4-0.log\n912-MIPFocus2-Presolve1-TimeLimit600-glass4-1.log\n912-MIPFocus2-Presolve1-TimeLimit600-glass4-2.log\n912-Presolve1-TimeLimit600-glass4-0.log\n912-Presolve1-TimeLimit600-glass4-1.log\n912-Presolve1-TimeLimit600-glass4-2.log\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Gurobi log file tools for parsing and exploring data",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/Gurobi/grblogtools"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae03a1fec84bd6af9783d24601734d646ce8fd29a957dbe463f44b0930ad9a45",
"md5": "7963bc0e4e80584d7f360bf64d69eef7",
"sha256": "87496573b34cee87f040243dd2feeed4fc385a30e297bcabfb0136f8cc78b7c8"
},
"downloads": -1,
"filename": "grblogtools-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7963bc0e4e80584d7f360bf64d69eef7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 43921,
"upload_time": "2023-08-24T22:28:19",
"upload_time_iso_8601": "2023-08-24T22:28:19.735912Z",
"url": "https://files.pythonhosted.org/packages/ae/03/a1fec84bd6af9783d24601734d646ce8fd29a957dbe463f44b0930ad9a45/grblogtools-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d2e0a318eea59f9ab6e452ebe19937b5d5e644bba7c5b697f12dd5b6adcc024",
"md5": "cde9e7b174484fde2265f0cd37e4ce1e",
"sha256": "1eed848178823f75fb720913aae0e376320ea8eaf846d114db30e31b6aa21d14"
},
"downloads": -1,
"filename": "grblogtools-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "cde9e7b174484fde2265f0cd37e4ce1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26831,
"upload_time": "2023-08-24T22:28:21",
"upload_time_iso_8601": "2023-08-24T22:28:21.324543Z",
"url": "https://files.pythonhosted.org/packages/0d/2e/0a318eea59f9ab6e452ebe19937b5d5e644bba7c5b697f12dd5b6adcc024/grblogtools-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-24 22:28:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Gurobi",
"github_project": "grblogtools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "grblogtools"
}
JSON
