> For the complete documentation index, see [llms.txt](https://anufrievroman.gitbook.io/freepaths/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://anufrievroman.gitbook.io/freepaths/getting-started/usage.md).

# Usage

FreePATHS is a command-line application, so it runs inside Linux, macOS, or Windows terminal. It takes an input file or config file from the user, which contains all the settings, and outputs the results in a new folder. For an extensive guide on creating config files, please see [config-file-creation-guide.md](/freepaths/getting-started/config-file-creation-guide.md).

There are three modes of using the program.

* The **main mode** traces many phonons through a structure and collects statistics about their paths. This mode calculates the thermal flux and temperature profile of the sample and uses this to calculate effective thermal conductivity.
* The **MFP sampling mode** measures phonon mean free paths using a few phonons and calculates the thermal conductivity by integrating phonon dispersion.
* The **electron simulation** mode simulates electrons instead of the phonons.

### Demo

First, if you simply run `freepaths` without specifying an input file, the program will run a [demo simulation](/freepaths/basic-tutorials/nanowire.md) and output some demo results, so that you can take a look at what kind of results you can get.

### Main mode

In the main mode, the program traces many phonons through a structure and calculates various statistical distributions and maps. In this mode, the thermal conductivity will be calculated via Fourier law, as [explained here](/freepaths/theory/themal-conductivity-calculation.md#fourier-law-approach).

Run the program as:

```
freepaths your_input_file.py
```

In the `examples` folder, you will find example input files. Try using one of them, for instance, as:

```
freepaths nanowire.py
```

After the simulation, see the results in a newly created `Results` folder.

### Mean free path sampling mode

Alternatively, you can run FreePATHS in the mean free path sampling mode, which is designed to calculate the thermal conductivity by integrating phonon dispersion, as [explained here](/freepaths/theory/themal-conductivity-calculation.md#mean-free-path-approach). To run the program in this mode, reduce `NUMBER_OF_PARTICLES` to about 30 and add the `-s` flag in the command:

```
freepaths -s your_input_file.py
```

The thermal conductivity will be output in the terminal. However, other statistical quantities and plots will still be calculated and output in the `Results` folder.

### Electron transport mode

FreePATHS can also simulate electron transport and obtain electrical conductivity, [as explained here](/freepaths/theory/electrical-conductivity.md). To use this mode, add `-e` flag before your input file and don't forget to [set electron properties](/freepaths/getting-started/config-file-creation-guide.md#electron-parameters).

```
freepaths -e your_input_file.py
```

### Troubleshooting

* If simulations are too slow, try using [multiprocessing](/freepaths/getting-started/config-file-creation-guide.md#multiprocessing-parameter).
* If you experience crashes due to excessive memory usage, try `LOW_MEMORY_USAGE = True` parameter in the input file.
* Rarely, phonons may enter a hole in the structure or break out of structure boundaries. To reduce the impact of this bug, reduce the `TIMESTEP` parameter. However, this usually happens once per thousands of collisions and has a negligible impact on the final statistics.
* If you have an error similar to `Cannot mix incompatible Qt library (5.15.7) with this library (5.15.8)` it likely means that you have a program like `qt5-styleplugins` that didn't upgrade to the latest Qt library with the rest of the system.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://anufrievroman.gitbook.io/freepaths/getting-started/usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.