Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kmkolasinski/bubel-viewer
A simple 3D visualization tool for tight binding models
https://github.com/kmkolasinski/bubel-viewer
Last synced: 22 days ago
JSON representation
A simple 3D visualization tool for tight binding models
- Host: GitHub
- URL: https://github.com/kmkolasinski/bubel-viewer
- Owner: kmkolasinski
- License: mit
- Created: 2020-12-10T05:18:54.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2020-12-10T09:07:59.000Z (about 4 years ago)
- Last Synced: 2024-10-29T18:23:45.004Z (2 months ago)
- Language: C++
- Homepage:
- Size: 968 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Bubel-Viewer 2020-12-11
A simple 3D visualization tool for tight binding models
# Data format
## Representing Tight-Bingding system
Viewer can read XML file which has following structure which uses XML format. For
the reference see the system0_lattice.xml file.
```xml
# content of the system.xml file
POS_X POS_Y POS_Z FLAG_0 FLAG_1 FLAG_2 ACTIVE NUM_ORBITALS NUM_BOUNDS
...
FROM_ATOM_ID TO_ADOM_ID FROM_ORBITAL_I TO_ORBITAL_J RE_VALUE IM_VALUE
...
==> See explanation below
LEAD_DIRECTION_VECTOR_X LEAD_DIRECTION_VECTOR_Y LEAD_DIRECTION_VECTOR_Z
ATOM_ID
...
ATOM_ID
...
FROM_ATOM_ID TO_ADOM_ID FROM_ORBITAL_I TO_ORBITAL_J
...
FROM_ATOM_ID TO_ADOM_ID FROM_ORBITAL_I TO_ORBITAL_J
...
```
### Definitions:
Atom defintion:
* `POS_X POS_Y POS_Z` - a three float numbers denoting 3D position of the k-th atom
* `FLAG_0` - extra integer parameter which allows to distinguish atoms e.g. from different sub-latticies, can be used
to control the rendering color of the atoms with different flagsm which may help in debugging.
* `FLAG_1` - extra integer parameter which will be displayed in the Viewer
* `FLAG_2` - extra integer parameter which will be displayed in the Viewer
* `ACTIVE` - a number (0, 1), in most cases this value should be set to 1.
* `NUM_ORBITALS` - a number of degress of freedom e.g. spin-orbitals
* `NUM_BOUNDS` - a number of connections between other atoms
Coupling definition (a graph egde):
* `FROM_ATOM_ID` - integer index of the source atom in the atoms list (**starting from 1**)
* `TO_ADOM_ID` - integer index of the target atom in the atoms list (**starting from 1**)
* `FROM_ORBITAL_I` - a number between (1, ATOMS[FROM_ATOM_ID].NUM_ORBITALS) denoting the coupling between possible degress of freedom
* `TO_ORBITAL_J` - a number between (1, ATOMS[TO_ADOM_ID].NUM_ORBITALS) denoting the coupling between possible degress of freedom
* `RE_VALUE IM_VALUE` - two float numbers denoting coupling value Re(coupling_value) Im(coupling_value) between from and to atoms and their orobitals.
Lead definition (this section is optional in the XML) it allows to render extra information about translational invariant leads
used in the Quantum Transport problems.
* `` - XML data with lead shape definition, see section below for avaiable options
* `LEAD_DIRECTION_VECTOR_X LEAD_DIRECTION_VECTOR_Y LEAD_DIRECTION_VECTOR_Z` - lead direction vector a unit cell translation vector
* `` - `ATOM_ID` - index of the atom which belongs to the lead part from the global atoms list, enumrated from 1.
* `` - `ATOM_ID` - index of the atom which belongs to the lead part, but comes from the next unit cell, from the global atoms list, enumrated from 1.
* `` - `FROM_ATOM_ID TO_ADOM_ID FROM_ORBITAL_I TO_ORBITAL_J` - integer values with graph defintion for connections between lead atoms and next unit cell.
* `` - `FROM_ATOM_ID TO_ADOM_ID FROM_ORBITAL_I TO_ORBITAL_J` - integer values with graph defintion for connections inside unit cell.
###
Lead type depends on the Lead definition and will affect the rendering of
the lead in the viewer. Currently supported shape_type are:
* SHAPE_RECTANGLE_XY - lead definition valid for 2D systems i.e. a bounding box of the lead atoms in the XY plane.
```xml
SHAPE_RECTANGLE_XY
X_MIN Y_MIN X_MAX Y_MAX
```
* SHAPE_RANGE_3D - describe lead by its base position point and the unit cell translation vector
```xml
SHAPE_RECTANGLE_XY
BASE_POS_X BASE_POS_Y BASE_POS_Z LEAD_DIRECTION_VECTOR_X LEAD_DIRECTION_VECTOR_Y LEAD_DIRECTION_VECTOR_Z
```
## Rendering onsite data
TODO - viewer has limited possibilies to render onside data like electron density, see example file: system0_densities1.xml for
required structure.
# Building the Source Code
## Requirements
The application has been tested on linux Ubuntu 18 LTS system, however since it
is purely written in Qt a crossplatform it should also work on other systems.
Program has been compiled with:
* Qt 5.15.2 GCC 64bit
* Additional OpenGL related libraries may be required for building, for linux see e.g. this [thread](https://forum.qt.io/topic/50865/gl-gl-h-not-found-in-linux/10)
## Builing steps
* The application must be compiled from source
* Download and install QtCreator - https://www.qt.io/download (follow "Downloads for open source users")
* Start QtCreator application
* Select **Open Project** and navigate to **bubel-viewer/src/viewer.pro** file.
* Select supported by your system compiler and press **Configure Project**
* Build Project (optionally switch to the Release mode for greater performance) by pressing **hammer button** in the bottom-left corner.
* After compilation Run application, by clicking green **play button** in the bottom-left corner.
* Navigate to the sample model folder and drag and drop "samples/sample_model.xml" file into viewer window it should open the
file with simple thight-binding model.
* After this step, you can find binary file **viewer** or **viewer.exe** in the **bubel/viewer/build-viewer-.../** folder.
You should be able to run viewer by double clicking on this icon.