FSvisual

FSvisual is a software tool to visualize Fermi surfaces—the boundaries between occupied and unoccupied electronic states in metals.

It is capable of creating interactive 3D Fermi surface visualizations on a 2D screen as an html file format. The visualizations are interactive and can be viewed in any modern web browser, as shown in the image below with the Fermi surface of Be as an example.

The significance of Fermi surfaces arises from a fundamental physical principle: Only energy states in close proximity to the Fermi surface can actively participate in a material’s response to external stimuli at temperatures around and below room temperature. Consequently, the topology and characteristics of Fermi surfaces strongly determine many material properties, including electronic, optical, thermal, and magnetic properties.

Table of Contents

• Installation
• Usage
• Dependencies
• Contributing
• License

Installation

Installation using pip (recommended!)

First make sure that pip and python3 are installed.

It is good practice to install software like FSvisual in a dedicated python environment, which we will create now:

Go use cd commands to move to a desired directory on your device for the installation, then enter

python3 -m venv fsvisual_env

The environment name fsvisual_env can freely be chosen to another name!

Next, we need to activate the environment, which needs to be done each time FSvisual is being used:

source fsvisual_env/bin/activate

This is the path from the directory where the environment was created in. If you are in a different directory you first have to move back!

Now, we are all set for the installation of FSvisual:

pip install fsvisual

Installation in dedicated python environment using git

First, make sure git and python3 are installed. If so, we now start by cloning the FSvisual repository to a local directory (a folder on your system). You now have to choose a folder to store the repository. Move to that location with the cd command. Once you arrived at the desired location, paste the command

git clone https://git.physik.hu-berlin.de/stutzjan/fsvisual

and hit enter. Now move into the newly created folder FSvisual with cd fsvisual.

Next, we create a virtual environment in which we install FSvisual:

python3 -m venv fsvisual_env

After creation, we also have to activate the environment.

source fsvisual_env/bin/activate

deactivate other active environments if there are any.

With the virtual environment set up, we can now install FSvisual by pasting

pip install .

into the console.

Note: Since FSvisual is installed in the newly created virtual environment, it only works when this environment is active. So the command

Post Installation

When the installation is finished, check if FSvisual is working using the command

fsvisual --help

If everything was successful, you should see every possible CLI command of FSvisual with a short explanation printed to the console.

source fsvisual_env/bin/activate

has to be run whenever you want to use FSvisual.

Usage

After the installation, FSvisual can be launched via a command line interface (CLI) by typing the command fsvisual into your console. FSvisual requires you to provide a directory or file path to your Fermi surface file/files. Currently, FSvisual only supports Fermi surface data in the .bxsf file format, which was established by visualization software XCrySDen and is now widely adopted by software supporting Fermi surface calculation, including exciting. In the following you can find an example on how to correctly call FSvisual together with one of its optional arguments.

fsvisual "bxsf_file_or_directory_path" -sf "save_path"

This command starts the visualization of the Fermi surface calculations stored in the specified directory, and saves them to the specified save_path. By typing fsvisual -h you get a list of all available arguments along with an explanation on how to use them:

usage: fsvisual [-h] [-sf SAVE_FERMISURFACES] [-s SUBDIVISION_SURFACE] [-dp DOWNSAMPLING_SURFACE_PERCENTAGE] [-df DOWNSAMPLING_SURFACE_FACE]
                [-wl WIDTH_LINE_BZ] [-c] [--force] [--show] [--dont_show]
                bxsf_files_directory

positional arguments:
  bxsf_files_directory  directory (folder) where the .bxsf files (Fermisurface files) are stored

options:
  -h, --help            show this help message and exit
  -sf, --save_fermisurfaces SAVE_FERMISURFACES
                        directory where visualized Fermi surfaces are stored
  -s, --subdivision_surface SUBDIVISION_SURFACE
                        divides every triangle of the Fermi surface mesh into two triangles; executes as many times as the input says
  -dp, --downsampling_surface_percentage DOWNSAMPLING_SURFACE_PERCENTAGE
                        lowers the resolution of the Fermi surface mesh (number of faces) to a given percentage (from original face count)
  -df, --downsampling_surface_face DOWNSAMPLING_SURFACE_FACE
                        lowers the resolution of the Fermi surface mesh (number of faces) to a given face number
  -wl, --width_line_BZ WIDTH_LINE_BZ
                        adjusts the width of the Brillouin zone lines
  -c, --create_SVG      boolean whether to create SVG files
  --force               if bandstructure files do not end with .bxsf, but are still correctly formatted, forcing FSvisual to parse those files is
                        possible
  --show                Fermi surfaces are immediately shown in Browser
  --dont_show           Deactivates the default that if only 1 Fermi surface is created, it is always shown in Browser

Once the Fermi surfaces of interest are visualized and opened in a web browser of choice, the camera view of every surface can be rotated by holding the left mouse button and dragging the cursor in the desired direction. Holding the right mouse button (or pressing the control key on the keyboard + left mouse button) locks the vertical axis of the camera. Subsequent movements will translate the camera along the horizontal axes. Any alteration of the camera position can be reset by reloading the page. The user can zoom in and out using the mouse wheel. An interactive legend is located in the upper-right corner of the screen. By clicking the entries in the legend, the user can either hide or show the first Brillouin zone as well as the different surface parts that are contributions from different energy bands to the Fermi surface. This functionality is illustrated in the image below.

Dependencies

Package	Version	Link
Python	≥ 3.9	python.org
pandas	≥ 2.3.1	pandas.pydata.org
numpy	≥ 2.3.1	numpy.org
trimesh	≥ 4.7.4	trimesh.org
pymeshlab	≥ 2023.12.post3	pymeshlab.readthedocs.io
scikit-image	≥ 0.25.2	scikit-image.org
requests	≥ 2.32.4	python-requests.org
pymatgen	≥ 2025.6.14	pymatgen.org
plotly	≥ 6.3.0	plotly.com
shapely	≥ 2.1.1	shapely
kaleido	≥ 1.0.0	kaleido

Contributing

Pull requests are welcome! For major changes, please open an issue first.

License

This project is licensed under the GNU General Public License.