# PyEnergyDiagrams
[](https://zenodo.org/badge/latestdoi/79893385)
`energydiagram` Python module for plotting energy profile diagrams using Matplotlib.
## Installation
If you are new to Python, the easiest way to get started is to use a distribution like [Anaconda](https://www.anaconda.com/). Then you can use the terminal to install the module using pip:
pip install energydiagram
For installing the development version:
pip install git+https://github.com/giacomomarchioro/PyEnergyDiagrams
The only requirement is [matplotlib](http://matplotlib.org/users/installing.html), which is installed by default using Anaconda.
## How to use it?
```python
from energydiagram import ED
diagram = ED()
diagram.round_energies_at_digit = 2
diagram.bottom_text_fontsize = 'small'
diagram.top_text_fontsize = 'small'
diagram.offset = 2
diagram.add_level(0, 'Separated\nReactants')
diagram.add_level(-5.4, 'mlC1')
diagram.add_level(-15.6, 'mlC2', 'last',) #Using 'last' or 'l' it will be together with the previous level
diagram.add_level(28.5, 'mTS1', color='g')
diagram.add_level(-9.7, 'mCARB1')
diagram.add_level(-19.8, 'mCARB2', 'last')
diagram.add_level(20, 'mCARBX', 'last')
```
Show the IDs (red numbers) to understand how to link the levels:
```python
diagram.plot(show_IDs=True)
```
Add the links using `diagram.add_link(starting_level_ID,ending_level_ID)`:
```python
diagram.add_link(0, 1, color='r')
diagram.add_link(0, 2)
diagram.add_link(2, 3, color='b', line_order=2) # change line order to make a curved link
diagram.add_link(1, 3, line_order=2)
diagram.add_link(3, 4, color='g', line_order=2)
diagram.add_link(3, 5, line_order=2)
diagram.add_link(0, 6, line_order=3)
# now we create the plot, this will update the figure
diagram.plot(ylabel="Energy / $kcal$ $mol^{-1}$") # this is the default ylabel
```
To show it you can use `diagram.fig.show()` while for saving it use `diagram.fig.savefig('myEnergyDiagra.pdf')`.
## Electron boxes
The electron boxes can be added using:
```python
diagram.add_electronbox(level_id=0, boxes=1, electrons=2, side=3, spacing_f=3)
diagram.add_electronbox(3, 3, 1, 3, 3)
diagram.add_electronbox(5, 3, 5, 3, 3)
```
The electron spin is automatically changed following the aufbau principle.
```python
from energydiagram import ED
diagram2 = ED()
diagram2.add_level(0,'2pxy',top_text='')
diagram2.add_level(10,r'$\sigma*$',top_text='')
diagram2.add_level(5,r'$\pi*$','last',top_text='')
diagram2.add_level(-5,r'$\pi$','last',color='g',top_text='')
diagram2.add_level(-10,r'$\sigma$',top_text='',position='l')
diagram2.add_level(0,'2pxy',top_text='')
for i in range(1,5):
diagram2.add_link(0,i,color='g')
diagram2.add_link(i,5,color='b')
diagram2.add_electronbox(level_id=0, boxes=1, electrons=2, side=1.5, spacing_f=2.5)
diagram2.add_electronbox(1,2,0,1.5,3)
diagram2.add_electronbox(2,5,10,1.5,3)
diagram2.add_electronbox(3,3,4,1.5,3)
diagram2.add_electronbox(4,3,2,1.5,3)
diagram2.add_electronbox(5,3,5,1.5,3)
diagram2.offset *= 1.5
diagram2.plot()
```
## Arrows between levels
You can caluclate the energy betwen two layers and show arrows using:
```python
diagram.add_arrow(3, 4, position='left', color='blue')
diagram.add_arrow(6, 4, position='center')
diagram.add_arrow(5, 4, position='right', color='r')
```
## Troubleshooting and fine-tuning
Most of the time, there could be a problem with text padding. Some parameters can be changed in this way.
```python
diagram.offset = 10
```
To make the change effective, you must use the command `diagram.plot()` again. Remember that once you have made a first attempt at plotting. You can adjust the plot as every matplotlib plot. For convenience you can access `ax` and `fig` from the instance of the class.
```python
# we adjust some parameters
diagram.ax.set_ylabel('My label')
diagram.fig.set_figwidth(10)
# don't want tikcs on the y label
diagram.ax.set_yticks([])
# I want to show on the x axis instead
diagram.ax.axes.get_xaxis().set_visible(True)
diagram.ax.spines['bottom'].set_visible(True)
diagram.ax.set_xlabel("My x label")
# we replot the figure (sometimes we have to resize with the mouse the figure so we force to refresh)
# diagram.fig.show()
```
If you use the command `diagram.plot()` now all the changes will be overwritten, so these minor adjustment must be done after.
## Testing
```bash
python3.12 -m unittest tests/test_energydiagram.py
```
### Contributors
Thanks to Kalyan Jyoti Kalita for the arrow functionality and O2-AC, agrass15268 for bug fixing.
Raw data
{
"_id": null,
"home_page": null,
"name": "energydiagram",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "energy diagram, matplotlib, chemistry, visualization",
"author": null,
"author_email": "Giacomo Marchioro <giacomomarchioro@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/c1/60/d83f99d524988b378eb9bbb9086e5789b30473e20f37da2ae2b1b0911372/energydiagram-1.0.0.tar.gz",
"platform": null,
"description": "# PyEnergyDiagrams\n[](https://zenodo.org/badge/latestdoi/79893385)\n\n`energydiagram` Python module for plotting energy profile diagrams using Matplotlib.\n\n\n## Installation\nIf you are new to Python, the easiest way to get started is to use a distribution like [Anaconda](https://www.anaconda.com/). Then you can use the terminal to install the module using pip:\n\n pip install energydiagram\n\nFor installing the development version:\n\n pip install git+https://github.com/giacomomarchioro/PyEnergyDiagrams\n\nThe only requirement is [matplotlib](http://matplotlib.org/users/installing.html), which is installed by default using Anaconda.\n\n## How to use it?\n\n\n```python\nfrom energydiagram import ED\ndiagram = ED()\ndiagram.round_energies_at_digit = 2\ndiagram.bottom_text_fontsize = 'small'\ndiagram.top_text_fontsize = 'small'\ndiagram.offset = 2\ndiagram.add_level(0, 'Separated\\nReactants')\ndiagram.add_level(-5.4, 'mlC1')\ndiagram.add_level(-15.6, 'mlC2', 'last',) #Using 'last' or 'l' it will be together with the previous level\ndiagram.add_level(28.5, 'mTS1', color='g')\ndiagram.add_level(-9.7, 'mCARB1')\ndiagram.add_level(-19.8, 'mCARB2', 'last')\ndiagram.add_level(20, 'mCARBX', 'last')\n```\nShow the IDs (red numbers) to understand how to link the levels:\n\n```python\ndiagram.plot(show_IDs=True)\n```\n\n\nAdd the links using `diagram.add_link(starting_level_ID,ending_level_ID)`:\n```python\ndiagram.add_link(0, 1, color='r')\ndiagram.add_link(0, 2)\ndiagram.add_link(2, 3, color='b', line_order=2) # change line order to make a curved link\ndiagram.add_link(1, 3, line_order=2)\ndiagram.add_link(3, 4, color='g', line_order=2)\ndiagram.add_link(3, 5, line_order=2)\ndiagram.add_link(0, 6, line_order=3)\n# now we create the plot, this will update the figure\ndiagram.plot(ylabel=\"Energy / $kcal$ $mol^{-1}$\") # this is the default ylabel\n```\nTo show it you can use `diagram.fig.show()` while for saving it use `diagram.fig.savefig('myEnergyDiagra.pdf')`.\n\n## Electron boxes\nThe electron boxes can be added using:\n```python\ndiagram.add_electronbox(level_id=0, boxes=1, electrons=2, side=3, spacing_f=3)\ndiagram.add_electronbox(3, 3, 1, 3, 3)\ndiagram.add_electronbox(5, 3, 5, 3, 3)\n```\nThe electron spin is automatically changed following the aufbau principle.\n\n```python\nfrom energydiagram import ED\ndiagram2 = ED()\ndiagram2.add_level(0,'2pxy',top_text='')\ndiagram2.add_level(10,r'$\\sigma*$',top_text='')\ndiagram2.add_level(5,r'$\\pi*$','last',top_text='')\ndiagram2.add_level(-5,r'$\\pi$','last',color='g',top_text='')\ndiagram2.add_level(-10,r'$\\sigma$',top_text='',position='l')\ndiagram2.add_level(0,'2pxy',top_text='')\nfor i in range(1,5):\n diagram2.add_link(0,i,color='g')\n diagram2.add_link(i,5,color='b')\ndiagram2.add_electronbox(level_id=0, boxes=1, electrons=2, side=1.5, spacing_f=2.5)\ndiagram2.add_electronbox(1,2,0,1.5,3)\ndiagram2.add_electronbox(2,5,10,1.5,3)\ndiagram2.add_electronbox(3,3,4,1.5,3)\ndiagram2.add_electronbox(4,3,2,1.5,3)\ndiagram2.add_electronbox(5,3,5,1.5,3)\ndiagram2.offset *= 1.5\ndiagram2.plot()\n```\n\n## Arrows between levels\nYou can caluclate the energy betwen two layers and show arrows using:\n\n```python\ndiagram.add_arrow(3, 4, position='left', color='blue')\ndiagram.add_arrow(6, 4, position='center')\ndiagram.add_arrow(5, 4, position='right', color='r')\n```\n\n## Troubleshooting and fine-tuning\nMost of the time, there could be a problem with text padding. Some parameters can be changed in this way.\n```python\ndiagram.offset = 10\n```\n\n\nTo make the change effective, you must use the command `diagram.plot()` again. Remember that once you have made a first attempt at plotting. You can adjust the plot as every matplotlib plot. For convenience you can access `ax` and `fig` from the instance of the class.\n\n```python\n# we adjust some parameters\ndiagram.ax.set_ylabel('My label')\ndiagram.fig.set_figwidth(10)\n# don't want tikcs on the y label\ndiagram.ax.set_yticks([])\n# I want to show on the x axis instead\ndiagram.ax.axes.get_xaxis().set_visible(True)\ndiagram.ax.spines['bottom'].set_visible(True)\ndiagram.ax.set_xlabel(\"My x label\")\n# we replot the figure (sometimes we have to resize with the mouse the figure so we force to refresh)\n# diagram.fig.show()\n\n```\nIf you use the command `diagram.plot()` now all the changes will be overwritten, so these minor adjustment must be done after.\n\n## Testing\n\n```bash\npython3.12 -m unittest tests/test_energydiagram.py\n```\n\n\n### Contributors\nThanks to Kalyan Jyoti Kalita for the arrow functionality and O2-AC, agrass15268 for bug fixing.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool for plotting Energy Diagrams using Matplotlib.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/giacomomarchioro/PyEnergyDiagrams"
},
"split_keywords": [
"energy diagram",
" matplotlib",
" chemistry",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c3288d6f14a288197050bb603e3e9ba6067bf580d50d371562b5db3679cefab9",
"md5": "7d86922c04f41dd1b2f8913faa5ba1b5",
"sha256": "c8900ee9e149f75ce649f2c2a6aff6ca43766987d06e6bc55706e5435a169b49"
},
"downloads": -1,
"filename": "energydiagram-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d86922c04f41dd1b2f8913faa5ba1b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 9850,
"upload_time": "2025-07-25T13:51:14",
"upload_time_iso_8601": "2025-07-25T13:51:14.745308Z",
"url": "https://files.pythonhosted.org/packages/c3/28/8d6f14a288197050bb603e3e9ba6067bf580d50d371562b5db3679cefab9/energydiagram-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c160d83f99d524988b378eb9bbb9086e5789b30473e20f37da2ae2b1b0911372",
"md5": "960c18ac12feb55b3d14addd9a70d360",
"sha256": "b9f4c5fad83221a15a51ce740ff9271e8125fb00e54eaf3c7d42ea58b3201d11"
},
"downloads": -1,
"filename": "energydiagram-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "960c18ac12feb55b3d14addd9a70d360",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11276,
"upload_time": "2025-07-25T13:51:15",
"upload_time_iso_8601": "2025-07-25T13:51:15.765623Z",
"url": "https://files.pythonhosted.org/packages/c1/60/d83f99d524988b378eb9bbb9086e5789b30473e20f37da2ae2b1b0911372/energydiagram-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 13:51:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "giacomomarchioro",
"github_project": "PyEnergyDiagrams",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "energydiagram"
}
JSON
