ENVISIoN is an open source tool/toolkit for electron structure visualization developed in the Materials Design and Informatics unit in the Theoretical Physics division at the Department of Physics, Chemistry and Biology at Linköping University (LiU).
The main component of ENVISIoN is a set of Python scripts that allow the user to visualise electronic structure quantities from ab-initio calculations in the Inviwo visualization framework, developed at the Scientific Visualization Group at LiU. ENVISIoN also includes a standalone graphical user interface implemented using Electron. Presently the only well-supported electronic structure calculations are those generated by VASP.
ENVISIoN presently includes the following features: visualization of crystal structure, electron density, electron localisation function, partial charge density, band structure, density of states, partial density of states, pair correlation function, and Fermi surface visualization.
ENVISIoN is licenced under BSD 2-Clause “Simplified” License.
For more details about the contributions and devlopment history of ENVISIoN, see Contributors.
Contents
- 1 Install ENVISIoN from binaries
- 2 Build ENVISIoN from source
- 3 Using ENVISIoN
- 4 Setup a development environment
- 5 Package ENVISIoN for distribution
- 6 Contributors
Binary packages are provided for some systems/distributions (e.g. as .deb for Ubuntu Linux).
Packages called <something>-anaconda are recommended.
These packages requires you to first install the Anaconda distribution of Python 3.
After Anaconda is installed, download the appropriate packaged version of ENVISIoN from the releases page and install using your operating systems package manager.
You should now be able to start ENVISIoN using envision (and the ENVISIoN-adapted Inviwo using envision-inviwo) in your terminal.
If installing ENVISIoN from binaries does not work, or you want to be able to develop ENVISIoN yourself, then you may want to use the following instructions to build ENVISIoN from source code.
These following instructions assume the use of Ubuntu Linux 20.04. For other systems you can try to adapt these instructions, or jump to the next section that install the dependencies using Anaconda instead.
Install dependencies for ENVISIoN:
sudo apt install \ python3 python3-pip \ git \ python3-numpy python3-h5py python3-pybind11 python3-scipy python3-regex \ npm
Install dependencies for ENVISIoN GUI:
pip3 install pysimplegui sudo apt-get install python3-tk
Install dependencies for building Inviwo:
sudo apt install \
build-essential gcc-8 g++-8 cmake git freeglut3-dev xorg-dev \
openexr zlib1g zlib1g-dev \
qt5-default qttools5-dev qttools5-dev-tools \
python3 python3-pip \
libjpeg-dev libtiff-dev libqt5svg5-dev libtirpc-dev libhdf5-dev \
libpng-dev libglu1-mesa-dev libxrandr-dev \
libxinerama-dev libxcursor-dev
Check that you have access to Qt 5.12 or later by this command:
qmake --version
If you need to upgrade Qt beyond the version provided by the system, you can do so by following these instructions:
wget http://download.qt.io/official_releases/qt/5.12/5.12.2/qt-opensource-linux-x64-5.12.2.run chmod +x qt-opensource-linux-x64-5.12.2.run sudo ./qt-opensource-linux-x64-5.12.2.run qtchooser -install opt-qt5.12.2 /opt/Qt5.12.2/5.12.2/gcc_64/bin/qmake
Check that you have access to cmake 3.12.0 or later by this command:
cmake --version
Install system packages required by Anaconda. Follow the instructions here, but specifically for Ubuntu Linux:
sudo apt install libgl1-mesa-glx libegl1-mesa libxrandr2 \
libxrandr2 libxss1 libxcursor1 libxcomposite1 \
libasound2 libxi6 libxtst6 python3-tk
Furthermore, even with Anaconda, there are some additional system packages needed for building Inviwo:
sudo apt install build-essential gcc-8 g++-8
Download the latest Python 3 version of Anaconda and install it.
Create a conda environment with the needed dependencies:
conda create --name envision python=3 git pybind11 \
numpy scipy matplotlib markdown regex wxpython \
h5py hdf5 libpng libtiff jpeg cmake pysimplegui \
nodejs "qt>=5.12" "cmake>=3.12.0" -c conda-forge
conda activate envision
qtchooser -install envision "$CONDA_PREFIX/bin/qmake"
Note:
- When doing future builds of ENVISIoN in a new terminal, you must remember to activate the envision conda environment by the command conda activate envision.
Check that you have access to Qt 5.3 or later by this command:
qmake --version
If you need to upgrade Qt beyond the version provided by the system, you can do so by following these instructions:
wget http://download.qt.io/official_releases/qt/5.12/5.12.2/qt-opensource-linux-x64-5.12.2.run chmod +x qt-opensource-linux-x64-5.12.2.run sudo ./qt-opensource-linux-x64-5.12.2.run qtchooser -install opt-qt5.12.2 /opt/Qt5.12.2/5.12.2/gcc_64/bin/qmake
Check that you have access to cmake 3.12 or later by this command:
cmake --version
Create a directory under your home directory to build ENVISIoN:
mkdir ~/ENVISIoN cd ~/ENVISIoN
Note:
- You may of course build ENVISIoN in any directory of your choosing. However, the instructions below assumes the above path, which you will have to adjust accordingly.
Download ENVISIoN and install the electron-based gui dependencies:
git clone https://github.com/rartino/ENVISIoN cd ENVISIoN npm install
Note:
- This places the ENVISIoN source code in the directory ~/ENVISIoN/ENVISIoN, which is intended.
- The last command may issue security warnings. It should still be possible to build and run ENVISIoN despite these warnings, and you may want to do so the first time you try to build ENVISIoN to avoid unexpected build issues.)
Download and checkout the correct version of the Inviwo source:
cd ~/ENVISIoN git clone https://github.com/inviwo/inviwo cd inviwo git checkout v0.9.11
Install the Inviwo submodule dependencies (note: one repository has moved, which the first line fixes):
sed -i 's%https://github.com/live-clones/hdf5.git%https://github.com/HDFGroup/hdf5.git%' .gitmodules git submodule update --init --recursive
Apply the ENVISIoN patches to Inviwo:
git apply \ "$HOME/ENVISIoN/ENVISIoN/inviwo/patches/deppack_fix.patch" \ "$HOME/ENVISIoN/ENVISIoN/inviwo/patches/filesystem_env.patch" \ "$HOME/ENVISIoN/ENVISIoN/inviwo/patches/ftl_fix.patch" \ "$HOME/ENVISIoN/ENVISIoN/inviwo/patches/transferfunction_extras.patch" \ "$HOME/ENVISIoN/ENVISIoN/inviwo/patches/composite_add.patch"
Normal builds should use the following steps to execute the cmake build of inviwo. However, the subsection below presents an alternative build that rather than the system compilers uses compulers installed by Anaconda.
If you are using a Qt that is not the one provided by the system, you now need to select the version you want the build to use. You do not need to do this if you just installed Qt via the system package manager. However, if you followed the instructions to install dependencies via Anaconda above, you want to select the envision qt version. Select a Qt version by the following commands:
qtchooser -l export QT_SELECT=<qt version> eval `qtchooser --print-env`
Configure and build Inviwo (change /inviwo and /inviwo-build paths based on desired directories):
cd ~/ENVISIoN mkdir inviwo-build cd inviwo-build/ cmake -G "Unix Makefiles" \ -DCMAKE_C_COMPILER="gcc-8" \ -DCMAKE_CXX_COMPILER="g++-8" \ -DBUILD_SHARED_LIBS=ON \ -DIVW_USE_EXTERNAL_IMG=ON \ -DIVW_EXTERNAL_MODULES="$HOME/ENVISIoN/ENVISIoN/inviwo/modules" \ -DIVW_MODULE_CRYSTALVISUALIZATION=ON \ -DIVW_MODULE_GRAPH2D=ON \ -DIVW_MODULE_HDF5=ON \ -DIVW_USE_EXTERNAL_HDF5=ON \ -DIVW_MODULE_PYTHON3=ON \ -DIVW_MODULE_PYTHON3QT=ON \ -DIVW_MODULE_QTWIDGETS=ON \ -DIVW_PACKAGE_PROJECT=ON \ -DIVW_PACKAGE_INSTALLER=ON \ -S ../inviwo -B ./ make -j4
Note:
- The number in make -j4 is the number of simultaneous build processes to run. Usually the best choice is the number of CPU cores in your build system.
- If you are running into build errors, re-run make with make -j1 to make sure that the last printout pertains to the actual error.
In difference to the above build, this build tries to satisfy as many of the library dependencies as possible with Anaconda, rather than use system libraries.
Note:
- The last time we tested this installation path, it did not work but gave a late-stage compilation error. This will be investigated in the future.
Add the necessery libraries to the conda environment:
conda install libx11-devel-cos6-x86_64 libxrandr-devel-cos6-x86_64 libxinerama-devel-cos6-x86_64 \
libxcursor-devel-cos6-x86_64 libxrender-devel-cos6-x86_64 \
xorg-x11-proto-devel-cos6-x86_64 \
libxi-devel-cos6-x86_64 libxext-devel-cos6-x86_64 libglu \
libx11-devel-cos6-x86_64 libxcursor-cos6-x86_64 \
libxfixes-devel-cos6-x86_64 \
libxdamage-cos6-x86_64 libxxf86vm-cos6-x86_64 libxau-cos6-x86_64 \
libselinux-cos6-x86_64 libpng-devel-cos6-x86_64 zlib
Setup cmake the following way:
cd ~/ENVISIoN
mkdir inviwo-build
cd inviwo-build/
export QT_SELECT=envision
eval `qtchooser --print-env`
export LIBRARY_PATH="$CONDA_PREFIX/ext-lib:$CONDA_PREFIX/x86_64-conda_cos6-linux-gnu/sysroot/usr/lib64:$CONDA_PREFIX/lib"
export CPATH="$CONDA_PREFIX/x86_64-conda_cos6-linux-gnu/sysroot/usr/include/:$CONDA_PREFIX/include"
cmake -G "Unix Makefiles" \
-DCMAKE_EXE_LINKER_FLAGS="-Wl,-rpath-link,$LIBRARY_PATH" \
-DCMAKE_SHARED_LINKER_FLAGS="-Wl,-rpath-link,$LIBRARY_PATH" \
-DCMAKE_SYSTEM_PREFIX_PATH="$HOME/anaconda3/envs/envision" \
-DCMAKE_SYSTEM_LIBRARY_PATH="${LIBRARY_PATH//:/;}" \
-DCMAKE_C_COMPILER="gcc-8" \
-DCMAKE_CXX_COMPILER="g++-8" \
-DCMAKE_CXX_FLAGS="-isystem '$HOME/anaconda3/envs/envision/include'" \
-DCMAKE_C_FLAGS="-isystem '$HOME/anaconda3/envs/envision/include'" \
-DBUILD_SHARED_LIBS=ON \
-DIVW_USE_EXTERNAL_IMG=ON \
-DIVW_EXTERNAL_MODULES="$HOME/ENVISIoN/ENVISIoN/inviwo/modules" \
-DIVW_MODULE_CRYSTALVISUALIZATION=ON \
-DIVW_MODULE_GRAPH2D=ON \
-DIVW_MODULE_HDF5=ON \
-DIVW_USE_EXTERNAL_HDF5=ON \
-DIVW_MODULE_PYTHON3=ON \
-DIVW_MODULE_PYTHON3QT=ON \
-DIVW_MODULE_QTWIDGETS=ON \
-DIVW_PACKAGE_PROJECT=ON \
-DIVW_PACKAGE_INSTALLER=ON \
../inviwo
make -j4
Note:
- The last time we tested this installation path, it did not work but gave a late-stage compilation error. This will be investigated in the future.
First add the necessary libraries to the conda environment by following the conda install command in the previous section.
Add the compilers to the conda environment:
conda install gcc_linux-64=7 gxx_linux-64=7
Setup cmake the following way:
cd ~/ENVISIoN
mkdir inviwo-build
cd inviwo-build/
export QT_SELECT=envision
eval `qtchooser --print-env`
export LIBRARY_PATH="$CONDA_PREFIX/ext-lib:$CONDA_PREFIX/x86_64-conda_cos6-linux-gnu/sysroot/usr/lib64:$CONDA_PREFIX/lib"
export CPATH="$CONDA_PREFIX/x86_64-conda_cos6-linux-gnu/sysroot/usr/include/:$CONDA_PREFIX/include"
cmake -G "Unix Makefiles" \
-DCMAKE_EXE_LINKER_FLAGS="-Wl,-rpath-link,$LIBRARY_PATH" \
-DCMAKE_SHARED_LINKER_FLAGS="-Wl,-rpath-link,$LIBRARY_PATH" \
-DCMAKE_SYSTEM_PREFIX_PATH="$HOME/anaconda3/envs/envision" \
-DCMAKE_SYSTEM_LIBRARY_PATH="${LIBRARY_PATH//:/;}" \
-DCMAKE_C_COMPILER="x86_64-conda_cos6-linux-gnu-gcc" \
-DCMAKE_CXX_COMPILER="x86_64-conda_cos6-linux-gnu-g++" \
-DCMAKE_CXX_FLAGS="-isystem '$HOME/anaconda3/envs/envision/include'" \
-DCMAKE_C_FLAGS="-isystem '$HOME/anaconda3/envs/envision/include'" \
-DIVW_HDF5_USE_EXTERNAL:BOOL=ON \
-DIVW_IMG_USE_EXTERNAL:BOOL=ON \
-DIVW_EXTERNAL_MODULES="$HOME/ENVISIoN/ENVISIoN/inviwo/modules" \
-DIVW_MODULE_CRYSTALVISUALIZATION=ON \
-DIVW_MODULE_FERMI=OFF \
-DIVW_MODULE_GRAPH2D=ON \
-DIVW_MODULE_PYTHON3=ON \
-DIVW_MODULE_PYTHON3QT=ON \
-DIVW_MODULE_QTWIDGETS=ON \
-DIVW_MODULE_HDF5=ON \
-DIVW_PACKAGE_PROJECT=ON \
-DIVW_PACKAGE_INSTALLER=ON \
../inviwo
make -j4
Start Inviwo to make sure it built properly:
cd ~/ENVISIoN inviwo-build/bin/inviwo
Quit Inviwo and then start the ENVISIoN GUI to see that it works:
cd ~/ENVISIoN/ENVISIoN export INVIWO_HOME="$HOME/ENVISIoN/inviwo-build/bin" npm start
For more details on how to use the ENVISIoN application than given here, see the User's guide.
If ENVISIoN was built using the instructions in this document, start it this way:
cd ~/ENVISIoN/ENVISIoN/envisionGUI export INVIWO_HOME="$HOME/ENVISIoN/inviwo-build/bin" python3 gui.py
ENVISIoN is implemented as python 3 scripts that do visualisations in Inviwo. For development work or to access more visualization features, the ENVISIoN scripts can be run directly inside the main Inviwo GUI. This is, however, less user-firendly than the dedicated ENVISIoN GUI.
If ENVISIoN was installed from binaries, it should be possible to start the ENVISIoN-enabled Inviwo GUI by:
envision-inviwo
If ENVISIoN was build from source using the instructions in this document, start it this way:
cd ~/ENVISIoN inviwo-build/bin/inviwo
Running an ENVISIoN visualisation from the Inviwo GUI is done by the following steps:
- Open up the Inviwo python editor.
- Click button to open a python file.
- A dialog prompts you to pick a file.
Scripts for visualisations are located in the directory
scriptsin your ENVISIoN directory (~/ENVISIoN/ENVISIoN/scripts). Pick the script for what you want to visualise. - Configure the paths in the python file to correspond to where you have installed ENVISIoN, where your VASP output data is, and where you wish to save the resulting HDF5 file.
A visualisation should now start. The visualisation can now be configured using the Inviwo network editor.
If ENVISIoN was installed from binaries, it should be possible to start simply by:
envision
You should now see the main window from where ENVISIoN can be controlled.
If ENVISIoN was build from source using the instructions in this document, start it this way:
cd ~/ENVISIoN/ENVISIoN export INVIWO_HOME="$HOME/ENVISIoN/inviwo-build/bin" npm start
Install needed files for eclipse:
sudo apt-get install gitg sudo apt-get install eclipse eclipse-pydev eclipse-cdt eclipse-cdt-qt
Create an Eclipse cmake project:
eval `qtchooser --print-env`
mkdir -p ~/ENVISIoN/inviwo.eclipse
cd ~/ENVISIoN/inviwo.eclipse
cmake -G "Eclipse CDT4 - Unix Makefiles" \
\
-DCMAKE_EXE_LINKER_FLAGS="-Wl,-rpath-link,$LIBRARY_PATH" \
-DCMAKE_SHARED_LINKER_FLAGS="-Wl,-rpath-link,$LIBRARY_PATH" \
-DCMAKE_SYSTEM_PREFIX_PATH="$HOME/anaconda3/envs/envision" \
-DCMAKE_SYSTEM_LIBRARY_PATH="${LIBRARY_PATH//:/;}" \
-DCMAKE_C_COMPILER="gcc-8" \
-DCMAKE_CXX_COMPILER="g++-8" \
-DCMAKE_CXX_FLAGS="-isystem '$HOME/anaconda3/envs/envision/include'" \
-DCMAKE_C_FLAGS="-isystem '$HOME/anaconda3/envs/envision/include'" \
-DIVW_HDF5_USE_EXTERNAL:BOOL=ON \
-DIVW_IMG_USE_EXTERNAL:BOOL=ON \
-DIVW_EXTERNAL_MODULES="$HOME/ENVISIoN/ENVISIoN/inviwo/modules" \
-DIVW_MODULE_CRYSTALVISUALIZATION=ON \
-DIVW_MODULE_FERMI=OFF \
-DIVW_MODULE_GRAPH2D=ON \
-DIVW_MODULE_PYTHON3=ON \
-DIVW_MODULE_PYTHON3QT=ON \
-DIVW_MODULE_QTWIDGETS=ON \
-DIVW_MODULE_HDF5=ON \
-DIVW_PACKAGE_PROJECT=ON \
-DIVW_PACKAGE_INSTALLER=ON \
\
-DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE \
-DCMAKE_ECLIPSE_MAKE_ARGUMENTS=-j5 \
-DCMAKE_ECLIPSE_VERSION=3.8.1 \
-DIVW_PROFILING=ON
Where the upper section is the same for a regular build (here using an Anaconda setup, but it can be replaced with a cmake run for using system dependencies instead). The lower section are eclipse-development-specific settings.
Note: other options for CMAKE_BUILD_TYPE are: Release, RelWithDebInfo, MinSizeRel.
Now start eclipse:
eclipse
Do the following:
- Close the welcome screen.
- Uncheck 'Project -> Build Automatically'
- File -> Import..., choose: Existing Projects into Workspace.
- For 'Select root directory' choose ENVISIoN/inviwo.eclipse in your home directory, eclipse should find the project.
- Click Finish.
- The project appear under inviwo-projects-Debug@inviwo.eclipse, in Project Explorer you'll find the source directory, i.e., inviwo.git, under '[Source directory]'. All modules, including the ENVISIoN ones show up under '[Subprojects]'.
- Click 'Build All' and inviwo should build.
- In the Project Explorer select bin/inviwo
- In the toolbar, click the drop-down arrow next to the green 'play' button and 'Run configurations...', select C/C++Application, and press the 'new' icon (a document with a star).
- The result should be a new Run configuration for bin/inviwo. Close the dialog.
- Press the green 'play' button in the toolbar, and Inviwo should run.
- Select File->New project. Select PyDev -> PyDev Project.
- Set the name to ENVISIoN
- For Project contents, unclick 'Use default', and browse to ENVISIoN/ENVISIoN in your home directory.
- Select Python version 3.
- Next + Finish (no referenced projects)
- Feel free to Switch to the PyDev perspective. (Perspectives are how menues etc. are organized to fit the programming language you work with. You switch perspective manually with buttons in the top right corner.)
- You can now browse with and work with the ENVISIoN python source files under the ENVISIoN project. (But work with the C++ modules under the Inviwo project.)
Another popular development environment is Visual Studio Code.
ENVISIoN can be built into an installable .deb package using the Dockerfile located in packaging/docker/. Generate packages by building the docker image and running it.
- Build the docker image to the required build step:
- docker build -f packaging/docker/Dockerfile --target envision_packager -t envision_packager .
- Run the docker image. It will copy the built packages to the directory it is run from. Change $(pwd) to something else to selet another directory:
- docker run -it --rm -v $(pwd):/package_output envision_packager
The initial version of ENVISIoN was developed the spring term 2017 as part of the course TFYA75: Applied Physics - Bachelor Project, given at Linköping University, Sweden (LiU) by Josef Adamsson, Robert Cranston, David Hartman, Denise Härnström, Fredrik Segerhammar. The project was supervised by Rickard Armiento (requisitioner and expert), Johan Jönsson (head supervisor), and Peter Steneteg (expert). The course examinator was Per Sandström.
ENVISIoN was further developed during the spring term of 2018 as part of the same course by Anders Rehult, Andreas Kempe, Marian Brännvall, and Viktor Bernholtz. The project was supervised by Rickard Armiento (requisitioner and expert), Johan Jönsson (head supervisor). The course examinator was Per Sandström.
Work on implementing visualization of partial electronic charge was done as a project work by Elvis Jacobson during the fall term of 2018.
ENVISIoN was further developed during the spring term of 2019 as part of the same course by: Linda Le, Abdullatif Ismail, Anton Hjert, Lloyd Kizito and Jesper Ericsson. The project was supervised by Rickard Armiento (requisitioner and expert), Johan Jönsson (head supervisor), and Peter Steneteg (expert). The course examiner was Per Sandström.
During summer 2019 the development was continued by Jesper Ericsson, primarily creating the Electron-based GUI.
ENVISIoN was further developed during the spring term of 2020 as part of the same course by: Alexander Vevstad, Amanda Aasa, Amanda Svennblad, Daniel Thomas, Lina Larsson and Olav Berg. The project was supervised by Rickard Armiento (requisitioner and expert), Joel Davidsson (head supervisor), and Peter Steneteg (expert). The course examiner was Per Sandström.
During summer 2020 the development was continued by Jesper Ericsson, primarily to simplify the code internals.
ENVISIoN was further developed during the spring term of 2021 as part of the same course by: Gabriel Anderberg, Didrik Axén, Adam Engman, Kristoffer Gubberud Maras and Joakim Stenborg The project was supervised by Rickard Armiento (requisitioner and expert), Marian Brännvall (head supervisor), and Peter Steneteg (expert). The course examiner was Per Sandström.