{"id":18435617,"url":"https://github.com/chpxu/exciting_plots","last_synced_at":"2025-07-25T19:39:14.948Z","repository":{"id":256564449,"uuid":"855731419","full_name":"chpxu/exciting_plots","owner":"chpxu","description":"Repository hosting modified plotting files I have made for data produced from exciting.","archived":false,"fork":false,"pushed_at":"2024-10-13T15:19:14.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-02-16T10:27:05.681Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chpxu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-11T11:26:30.000Z","updated_at":"2024-10-13T15:19:17.000Z","dependencies_parsed_at":"2024-09-11T19:12:09.723Z","dependency_job_id":"75f132e0-99d2-488c-85fd-d48e7bb3fe85","html_url":"https://github.com/chpxu/exciting_plots","commit_stats":null,"previous_names":["chpxu/exciting_plots"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpxu%2Fexciting_plots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpxu%2Fexciting_plots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpxu%2Fexciting_plots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chpxu%2Fexciting_plots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chpxu","download_url":"https://codeload.github.com/chpxu/exciting_plots/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248855198,"owners_count":21172510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T06:08:52.152Z","updated_at":"2025-04-14T09:39:25.439Z","avatar_url":"https://github.com/chpxu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# exciting_plots\nRepository hosting modified plotting files I have made for data produced from exciting. The following sections are documentation for each file. \n\nThe prescence of `readrawdata.py` is a necessity for PDOS and PBS to ensure maximum compatibility with previous versions of exciting.\n\nRequires lxml and matplotlib. `EVALCORE.OUT` should be present in the directory where you are trying to run these files.\n\n## PDOS\nTo plot PDOS, please add the attribute `lmirep = \"true\"` to the `\u003cdos\u003e` element and run `exciting`. Then, for every `\u003catom /\u003e` declared inside a `\u003cspecies\u003e` element, you will find files of the format `PDOS_Sxx_Ayyyy.OUT` where `Sxx` is the species number (indexed starting from `xx=01`, in the order that they were declared inside `input.xml`) and `Ayyyy` is the atom number (indexed starting from `yyyy=0001` in the order they were declared for its associated `\u003cspecies\u003e`). These will all be outputted in the directory where `exciting` was ran, typically in the same directory as `input.xml`.\n\n### Interpreting the PDOS OUT files\nIf you look inside `$EXCITINGROOT/species/*.xml` files, you will see all the different electronic states for your atoms: the 1s, 2s, 2p_x, 2p_y etc. In general, there are one s states, 3-p states, 5 d states, 7 f states and so on (i.e., all the s-states are considered together and so on).\n\nThe PDOS files are split into blocks of size `nwdos` (declared on the `\u003cdos\u003e` element) where the number of blocks equals the sum of the number of orbitals. If for example, the available states of any of your atoms goes up to and includes f states, and you have `nwdos=1000`, then you will have `(1 + 3 + 5 + 7)` blocks of `1000` data points. Every PDOS file has 2 columns, the first column is the energy in the range $[e_1, e_2]$ (declared by `winddos=\"e_1 e_2\"`) and the 2nd column is the PDOS at that point in states/Ha/unit cell. Therefore:\n- The total s-contribution from an atom of a species is given by the first block\n- The total p-contribution from an atom of a species is given by the sum of the 2nd,3rd,4th blocks\n- The total d-contribution from an atom of a species is given by the sum of the 5th-9th blocks inclusive.\n- And so on\n\nFor multiple atoms of the same species, the blocks are then added together to give the total orbital contribution from a species.\n\n### Using `pdos.py`\nThe file to call is `pdos.py` and should work for Python `\u003e= 3.7`, NumPy `\u003c 2`. Not tested with NumPy `2.x`. Example usage:\n```sh\npython3 pdos.py -f [files] -e -2 6 -db 0 2.5\n```\n\n- `-f` is the list of PDOS files. Order does not matter - it sorts them In the future, can just make a function to automatically find PDOS files.\n- `-e` is the energy range, i.e. x-axis range\n- `-db` is the y-axis (DOS) range. Note that the data is automatically converted to states/eV/unit cell\n\n\n## Projected Bandstructure (PBS)\nTo plot PBS, please add the attribute `character=\"true\"` to the `\u003cbandstructure\u003e` element and run `exciting`. Then, for every `\u003catom /\u003e` declared inside a `\u003cspecies\u003e` element, you will find files of the format `BAND_Sxx_Ayyyy.OUT` where `Sxx` is the species number (indexed starting from `xx=01`, in the order that they were declared inside `input.xml`) and `Ayyyy` is the atom number (indexed starting from `yyyy=0001` in the order they were declared for its associated `\u003cspecies\u003e`). These will all be outputted in the directory where `exciting` was ran, typically in the same directory as `input.xml`.\n\n### Interpreting the BAND files\nIf you look inside `$EXCITINGROOT/species/*.xml` files, you will see all the different electronic states for your atoms: the 1s, 2s, 2p\\_x, 2p\\_y etc. In general, there are one s states, 3-p states, 5 d states, 7 f states and so on (i.e., all the s-states are considered together and so on).\n\nThe BAND files are split into blocks of size `steps` (declared on the `\u003cpath\u003e` element) where the number of blocks equals the number of bands. Every BAND file has $3 + N\\_s$  columns ($N\\_s$ is the number of species), the first column is the KPATH, the 2nd column is the energy in the range $[e_1, e_2]$  and the 3rd column is the sum of the contributions for each k-point. Therefore:\n- The total s-contribution at a k-point from an atom of a species is given by the 4th column\n- The total p-contribution at a k-point from an atom of a species is given by the sum of the 5th column\n- The total d-contribution at a k-point from an atom of a species is given by the sum of the 6th column.\n- And so on\n\nFor multiple atoms of the same species, the blocks are then added together to give the total orbital contribution from a species.\n\n### Using `qp_weights.py`\nThe file to call is `qp_weights.py` and should work for Python `\u003e= 3.7`, NumPy `\u003c 2`. Not tested with NumPy `2.x`. Example usage:\n```sh\npython3 qp_weights.py -f [files] -y1 e_1 -y2 e_2 -s float | [float] -p \"cubic\" | \"hexagonal\" -shx \"none\" | \"all\" -shy \"none\" | \"all\" --norbitals 3 --scissor 0.0 | float\n```\n\n- `-f` is the list of BAND files. Order does not matter - it sorts them In the future, can just make a function to automatically find BAND files.\n- `-y1 -y2` is the energy range, i.e. y-axis range. Energy is automatically converted to eV.\n- `-p \"cubic\" | \"hexagonal\"` controls the x-axis tick labels for the path. Can be manually adjusted to your liking.\n- `-no, --norbitals` is the number of orbitals to plot. By default, it is 3 (s,p,d).\n- `-s`  is the scale factor. A single float scales the weights for all plots. Otherwise must be a list of floats of size $N\\_s \\times \\text{norbitals}$\n- `-shx` is \"none\" or \"all\" and controls whether each plot has its own labelled x-axis (\"none\") or shared.\n- `-shy` is \"none\" or \"all\" and controls whether each plot has its own labelled y-axis (\"none\") or shared.\n- `--scissor` is the scissor shift to apply to the conduction bands in eV.\n\nThis file will output bandstructures in a $N_s \\times \\text{norbitals}$ grid with a box in the top left containing the scale factor, and each plot labelled with species and orbital.\n\n## Exciton Weights\n\nExciton weights are a sum of absolute-squared BSE eigenvectors for electron-hole interactions. The logic for implementing visualisation is nearly identical to that of projectd bandstructures (see above).\n\n### Data files for exciton weights\nOnce you have run the appropriate `\u003cstoreexcitons\u003e`, `\u003cwriteexcitons\u003e` with the element `\u003cdoonly task=\"writekpathweights\" /\u003e` inside `\u003cplan\u003e`, a directory called `KPATHEXC` is created. Inside are 2 sets of files, for each exciton. These are `KPATH_\u003cBSEtype\u003e_QMTxxx_LAMBDAyyyyyy.OUT` and  `WEIGHTS_\u003cBSEtype\u003e_QMTxxx_LAMBDAyyyyyy.OUT` where `yyyyyy` is the exciton index. The `WEIGHTS` file stores the raw excitonic weights whilst `KPATH` contains the weights plotted along the BZ path of the  bandstructure. For visualisation, only the `KPATH` files matter.\n\nThe `KPATH` files have 3 columns: the kpath (the position along the BZ path), the energy of the bands and the excitonic weights in that order.\n\n### Using exciton_weights.py\nThis file is found in the `exciton` folder.\n\n Example usage:\n```sh\npython3 exciton_weights.py -f [files] -y1 e_1 -y2 e_2 -s float | [float] -p \"cubic\" | \"hexagonal\" -shx \"none\" | \"all\" -shy \"none\" | \"all\" -nr int -nc int --scissor 0.0 | float\n```\n\n- `-f` is the list of KPATH files. Order DOES matter - it will plot them as inputted.\n- `-y1 -y2` is the energy range, i.e. y-axis range. Energy is automatically converted to eV.\n- `-p \"cubic\" | \"hexagonal\"` controls the x-axis tick labels for the path. Can be manually adjusted to your liking.\n- `-s`  is the scale factor. A single float scales the weights for all plots. Otherwise must be a list of floats equal to the number of input files.\n- `-shx` is \"none\" or \"all\" and controls whether each plot has its own labelled x-axis (\"none\") or shared.\n- `-shy` is \"none\" or \"all\" and controls whether each plot has its own labelled y-axis (\"none\") or shared.\n- `--scissor` is the scissor shift to apply to the conduction bands in eV.\n- `-nr, -nc` control the number of rows and columns to plot respectively. It plots the graphs left-to-right and top-to-bottom. Note that these parameters will raise an error if `nr * nc != len(files)`.\n\nThis file will output bandstructures in a $n_r \\times n_c$ grid with a box in the top left containing the exciton index.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchpxu%2Fexciting_plots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchpxu%2Fexciting_plots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchpxu%2Fexciting_plots/lists"}