Metadata-Version: 2.4
Name: fsvisual
Version: 0.0.3
Summary: A Fermi surface visualization package
Author: FSvisual developers
Maintainer-email: Jan Stutz <stutzjan@physik.hu-berlin.de>, Martin Kuban <kuban@physik.hu-berlin.de>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/exciting/FSVisual
Project-URL: Issues, https://github.com/exciting/FSVisual/-/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.3.1
Requires-Dist: numpy>=2.3.1
Requires-Dist: trimesh>=4.7.4
Requires-Dist: pymeshlab>=2023.12.post3
Requires-Dist: scikit-image>=0.25.2
Requires-Dist: requests>=2.32.4
Requires-Dist: pymatgen>=2025.6.14
Requires-Dist: plotly>=6.3.0
Requires-Dist: shapely>=2.1.1
Requires-Dist: kaleido>=1.0.0
Requires-Dist: rich>=15.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# 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 <span style="font-family: monospace; font-weight: bold;">html</span>
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.


<div style="width: 100%; max-width: 1000px; margin: 0 auto;">
  <img
    src="images/Be_fermi_surface.png"
    alt="Fermi surface visualization of Be by `FSvisual`"
    style="width: 100%; height: auto; display: block;"
  >
</div>


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](#installation)
- [Usage](#usage)
- [Dependencies](#dependencies)
- [Contributing](#contributing)
- [License](#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:

Use the cd command to move to a desired directory on your device for the installation, then enter

```bash
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: 

```bash
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`:

```bash
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 

```bash
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`:

```bash
python3 -m venv fsvisual_env
```

After creation, we also have to activate the environment.

```bash
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

```bash
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

```bash
fsvisual --help
```

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



```bash
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 <span style="font-family: monospace; font-weight: bold;">exciting</span>.
In the following you can find an example on how to correctly call `FSvisual`
together with one of its optional arguments.

```bash
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.

<div style="width: 100%; max-width: 1000px; margin: 0 auto;">
  <img
    src="images/FSvisual_demo.png"
    alt="Illustrates the functionality to show and hide surface 
parts as well as the first Brillouin zone with the Legend"
    style="width: 100%; height: auto; display: block;"
  >
</div>

## Dependencies

<custom-element data-json="%7B%22type%22%3A%22table-metadata%22%2C%22attributes%22%3A%7B%22title%22%3A%22Dependencies%22%7D%7D" />

| Package   | Version | Link                                                                         |
|-----------|---------|------------------------------------------------------------------------------|
| Python    | ≥ 3.9   | [python.org](https://python.org)                                             |
| `pandas`  | ≥ 2.3.1 | [pandas.pydata.org](https://pandas.pydata.org/)                              |
| `numpy`   | ≥ 2.3.1  | [numpy.org](https://numpy.org)                                               |
| `trimesh` | ≥ 4.7.4   | [trimesh.org](https://trimesh.org/)                                          |
| `pymeshlab`| ≥ 2023.12.post3   | [pymeshlab.readthedocs.io](https://pymeshlab.readthedocs.io/en/latest/)      |
| `scikit-image`  | ≥ 0.25.2   | [scikit-image.org](https://scikit-image.org/)                                |
| `requests` | ≥ 2.32.4   | [python-requests.org](https://docs.python-requests.org/en/latest/index.html) |
| `pymatgen`| ≥ 2025.6.14   | [pymatgen.org](https://pymatgen.org/)                                        |
| `plotly`  | ≥ 6.3.0   | [plotly.com](https://plotly.com/python/)                                     |
| `shapely`| ≥ 2.1.1  | [shapely](https://github.com/shapely/shapely)                                |
| `kaleido`  | ≥ 1.0.0   | [kaleido](https://pypi.org/project/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](LICENSE).
