<img src="https://raw.githubusercontent.com/dihm/leveldiagram/main/docs/source/img/LevelDiagramLogo300.png" alt="leveldiagram" style="max-width: 100%;">
[](https://pypi.org/project/leveldiagram)
[](https://python.org)
[](https://github.com/dihm/leveldiagram/raw/main/LICENSE.md)
[](https://leveldiagram.readthedocs.io/en/latest)
# leveldiagram
This module creates energy level diagrams common to atomic physics as matplotlib graphics.
The level structure is defined using networkx graphs.
## Quick Usage
This package takes networkx directional graphs,
which can be used to effectively define a system hamiltonian,
and creates an energy diagram representing the system.
The nodes of the graph represent the energy levels.
The edges of the graph represent the couplings between levels.
Passing a simple graph to the basic level diagram constructor will produce a passable output for simple visualization purposes.
```python
nodes = (0,1,2)
edges = ((0,1),(1,2))
graph = nx.DiGraph()
graph.add_nodes_from(nodes)
graph.add_edges_from(edges)
d = ld.LD(graph)
d.draw()
```
Global settings for the three primitive objects used by leveldiagram can be set by passing keyword argument dictionaries to the `LD` constructor.
To control options for a single level or coupling,
save these keyword arguments to the respective node or edge of the supplied graph.
Generally, the levels and couplings take standard matplotlib 2D line configuration arguments.
```python
nodes = ((0,{'bottom_text':'ground'}),
(1,{'right_text':'excited'}),
(2,{'top_text':'rydberg'}))
edges = ((0,1, {'label':'$\\Omega_p$'}),
(1,2, {'label':'$\\Omega_c$'}))
graph = nx.DiGraph()
graph.add_nodes_from(nodes)
graph.add_edges_from(edges)
d = ld.LD(graph, coupling_defaults = {'arrowsize':0.15,'lw':3})
d.draw()
```
With some basic scripting to create the graph appropriately,
much more complicated level diagrams can be made with relative ease.
```python
hf_nodes = [((f,i), {('top' if f==2 else 'bottom') + '_text':'$m_F='+f'{i:d}'+'$',
'energy':f-1,
'xpos':i,
'width':0.75,
'text_kw':{'fontsize':'large'}})
for f in [1,2]
for i in range(-f,f+1)]
lin_couples = [((1,i),(2,i),{'label':l,'color':'C0',
'label_kw':{'fontsize':'medium','color':'C0'}})
for i,l in zip(range(-1,2), ['1/2','2/3','1/2'])]
sp_couples = [((1,i),(2,i+1),{'label':l,'color':'C1',
'label_offset':'right',
'label_kw':{'fontsize':'medium','color':'C1'}})
for i,l in zip(range(-1,2), ['1/6','1/2','1'])]
sm_couples = [((1,i),(2,i-1),{'label':l, 'color':'C2',
'label_offset':'left',
'label_kw':{'fontsize':'medium','color':'C2'}})
for i,l in zip(range(-1,2), ['1','1/2','1/6'])]
hf_edges = lin_couples + sp_couples + sm_couples
hf_graph = nx.DiGraph()
hf_graph.add_nodes_from(hf_nodes)
hf_graph.add_edges_from(hf_edges)
d = ld.LD(hf_graph, default_label = 'none')
d.ax.margins(y=0.2)
d.draw()
```
## Installation
Presently, installation must be done manually using a copy of the repository.
### Pure pip installation
To install in an editable way (which allows edits of the source code), run:
```shell
pip install -e .
```
from within the top level `leveldiagram` directory (i.e. where the `setup.cfg` file resides).
This command will use pip to install all necessary dependencies.
To install normally, run:
```shell
pip install .
```
from the same directory.
### Updating an existing installation
Upgrading an existing installation is simple.
Simply run the pip installation commands described above with the update flag.
```shell
pip install -U .
```
This command will also install any new dependencies that are required.
If using an editable install, simply replacing the files in the same directory is sufficient.
Though it is recommended to also run the appropriate pip update command as well.
```shell
pip install -U -e .
```
### Dependencies
Requires `matplotlib`, `networkx`, and `numpy`.
## Documentation
A PDF copy of the documentation is avaiable in the `docs/build/latex/` directory.
### Examples
Example jupyter notebooks that demonstrate leveldiagrams can be found in the `examples` subdirectory.
Printouts of these notebooks are available in the docs as well.
Raw data
{
"_id": null,
"home_page": null,
"name": "leveldiagram",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "physics, diagram, graph",
"author": "David Meyer",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/da/64/ddbb4d0227eb5b54552c072eabed7f2e5723753c537d8f0d32acf65d1e7d/leveldiagram-0.3.2.tar.gz",
"platform": null,
"description": "<img src=\"https://raw.githubusercontent.com/dihm/leveldiagram/main/docs/source/img/LevelDiagramLogo300.png\" alt=\"leveldiagram\" style=\"max-width: 100%;\">\n\n[](https://pypi.org/project/leveldiagram)\n[](https://python.org)\n[](https://github.com/dihm/leveldiagram/raw/main/LICENSE.md)\n[](https://leveldiagram.readthedocs.io/en/latest)\n\n# leveldiagram\n\nThis module creates energy level diagrams common to atomic physics as matplotlib graphics.\nThe level structure is defined using networkx graphs.\n\n## Quick Usage\n\nThis package takes networkx directional graphs,\nwhich can be used to effectively define a system hamiltonian,\nand creates an energy diagram representing the system.\nThe nodes of the graph represent the energy levels.\nThe edges of the graph represent the couplings between levels.\n\nPassing a simple graph to the basic level diagram constructor will produce a passable output for simple visualization purposes.\n\n```python\nnodes = (0,1,2)\nedges = ((0,1),(1,2))\ngraph = nx.DiGraph()\ngraph.add_nodes_from(nodes)\ngraph.add_edges_from(edges)\nd = ld.LD(graph)\nd.draw()\n```\n\n\nGlobal settings for the three primitive objects used by leveldiagram can be set by passing keyword argument dictionaries to the `LD` constructor.\nTo control options for a single level or coupling,\nsave these keyword arguments to the respective node or edge of the supplied graph.\nGenerally, the levels and couplings take standard matplotlib 2D line configuration arguments.\n\n```python\nnodes = ((0,{'bottom_text':'ground'}),\n (1,{'right_text':'excited'}),\n (2,{'top_text':'rydberg'}))\nedges = ((0,1, {'label':'$\\\\Omega_p$'}),\n (1,2, {'label':'$\\\\Omega_c$'}))\ngraph = nx.DiGraph()\ngraph.add_nodes_from(nodes)\ngraph.add_edges_from(edges)\nd = ld.LD(graph, coupling_defaults = {'arrowsize':0.15,'lw':3})\nd.draw()\n```\n\n\nWith some basic scripting to create the graph appropriately,\nmuch more complicated level diagrams can be made with relative ease.\n\n```python\nhf_nodes = [((f,i), {('top' if f==2 else 'bottom') + '_text':'$m_F='+f'{i:d}'+'$',\n 'energy':f-1,\n 'xpos':i,\n 'width':0.75,\n 'text_kw':{'fontsize':'large'}})\n for f in [1,2]\n for i in range(-f,f+1)]\nlin_couples = [((1,i),(2,i),{'label':l,'color':'C0',\n 'label_kw':{'fontsize':'medium','color':'C0'}})\n for i,l in zip(range(-1,2), ['1/2','2/3','1/2'])]\nsp_couples = [((1,i),(2,i+1),{'label':l,'color':'C1',\n 'label_offset':'right',\n 'label_kw':{'fontsize':'medium','color':'C1'}})\n for i,l in zip(range(-1,2), ['1/6','1/2','1'])]\nsm_couples = [((1,i),(2,i-1),{'label':l, 'color':'C2',\n 'label_offset':'left',\n 'label_kw':{'fontsize':'medium','color':'C2'}})\n for i,l in zip(range(-1,2), ['1','1/2','1/6'])]\nhf_edges = lin_couples + sp_couples + sm_couples\nhf_graph = nx.DiGraph()\nhf_graph.add_nodes_from(hf_nodes)\nhf_graph.add_edges_from(hf_edges)\nd = ld.LD(hf_graph, default_label = 'none')\nd.ax.margins(y=0.2)\nd.draw()\n```\n\n\n\n## Installation\n\nPresently, installation must be done manually using a copy of the repository.\n\n### Pure pip installation\n\nTo install in an editable way (which allows edits of the source code), run:\n```shell\npip install -e .\n```\nfrom within the top level `leveldiagram` directory (i.e. where the `setup.cfg` file resides).\nThis command will use pip to install all necessary dependencies.\n\nTo install normally, run:\n```shell\npip install .\n```\nfrom the same directory.\n\n\n### Updating an existing installation\n\nUpgrading an existing installation is simple.\nSimply run the pip installation commands described above with the update flag.\n```shell\npip install -U .\n```\nThis command will also install any new dependencies that are required.\n\nIf using an editable install, simply replacing the files in the same directory is sufficient.\nThough it is recommended to also run the appropriate pip update command as well.\n```shell\npip install -U -e .\n```\n\n### Dependencies\n\nRequires `matplotlib`, `networkx`, and `numpy`.\n\n## Documentation\n\nA PDF copy of the documentation is avaiable in the `docs/build/latex/` directory.\n\n### Examples\n\nExample jupyter notebooks that demonstrate leveldiagrams can be found in the `examples` subdirectory.\nPrintouts of these notebooks are available in the docs as well.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Energy level diagram plotting from graphs",
"version": "0.3.2",
"project_urls": null,
"split_keywords": [
"physics",
" diagram",
" graph"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be082a6da470fab488a8a54d5f3a12672872de60e2a7a88bd6e80e0f24044d99",
"md5": "d5396adde54446fd8119cd2cd7874f0a",
"sha256": "0186aad9f7fffa255beb4983af992423e5fbc2b0cbb5570e09d78fcac01920e9"
},
"downloads": -1,
"filename": "leveldiagram-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5396adde54446fd8119cd2cd7874f0a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13287,
"upload_time": "2024-10-02T19:57:05",
"upload_time_iso_8601": "2024-10-02T19:57:05.778955Z",
"url": "https://files.pythonhosted.org/packages/be/08/2a6da470fab488a8a54d5f3a12672872de60e2a7a88bd6e80e0f24044d99/leveldiagram-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "da64ddbb4d0227eb5b54552c072eabed7f2e5723753c537d8f0d32acf65d1e7d",
"md5": "c1f512ea543fc9cff6be317ead83d35d",
"sha256": "29a9d335e2c6e56a82b0e2c88b336a8723277ee071cece8b1a8f216ad53fc47c"
},
"downloads": -1,
"filename": "leveldiagram-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "c1f512ea543fc9cff6be317ead83d35d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 821191,
"upload_time": "2024-10-02T19:57:07",
"upload_time_iso_8601": "2024-10-02T19:57:07.157406Z",
"url": "https://files.pythonhosted.org/packages/da/64/ddbb4d0227eb5b54552c072eabed7f2e5723753c537d8f0d32acf65d1e7d/leveldiagram-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-02 19:57:07",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "leveldiagram"
}
JSON