Potku is a simulation and analysis software for Time-of-Flight Elastic Recoil Detection Analysis (ToF-ERDA). The software can be run on Windows, Linux and macOS.
This repository contains the Python source for the Qt 5 graphical user interface. Most of the number crunching is done by programs written in C. The source code of these is separate repositories on GitHub and are included as Git Submodules, please see the instructions below on how to acquire the source code and compile the C codes e.g. if you wish to develop Potku.
For most users it is recommended to download one of the ready to run (all dependencies included) binary packages, which are available on the releases page. Additionally older binary packages are available on the official website.
Copyright (C) 2013-2024 Potku developers
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
Please refer to the full license for details.
See the changelog for version history.
Install Git and add it to the PATH (on Windows).
Clone the repository and change your current working directory.
$ git clone --recursive https://github.com/JYU-IBA/potku.git
$ cd potku
Install the latest version of Python 3.12 along with pip package installer. Make
sure the paths of the executables are added to your PATH environment variable, i.e. you can run Python by running command python
.
Install Pipenv:
$ pip install --user pipenv
Install and activate the virtual environment with Pipenv:
$ pipenv install --dev
$ pipenv shell
Once the virtual environment is up and running, Potku GUI can be launched from the command line:
$ python potku.py
The graphical user interface won't be of much use without the C programs that perform the depth profiling and simulation. In order to compile them, requirements for JIBAL should be installed. All programs use CMake build system and are included as submodules in this repository.
Install cmake and gsl using the package manager of your distribution or homebrew. Then run the following:
$ cd dev
$ ./build.sh
to compile all programs. Note that this script has no error checking, if you encounter issues please check that all steps of the build have been successful.
For installing the requirements for JIBAL, follow the instructions.
- Note: instead of cloning the vcpkg master branch, you can also download the latest stable release from here and then continue with
.\vcpkg\bootstrap-vcpkg.bat
vcpkg.exe install gsl:x64-windows getopt:x64-windows
as instructed.
To compile the programs, run
cd dev
build.bat
If you get errors in the build, try different command prompt i.e. x64 Native Tools Command Prompt
as an administrator.
Also be sure that cmake
and vcpkg
are installed and in the PATH
.
JIBAL and Potku require additional data files. These can be either downloaded manually from
here or you can use the external_file_manager.py
in dev
to download the files.
These files need to be extracted to external/share/jibal
. You can run the
following command from the root folder of the repository to download and
extract the files. (note: curl
is not installed by default on all Windows versions)
$ curl http:https://users.jyu.fi/~jaakjuli/jibal/data/data.tar.gz -o data.tar.gz && tar -xvf data.tar.gz -C external/share/jibal
Tests are located in the tests
package. They are divided into unit tests
(tests that cover one or two functions at a time), integration tests
(tests that cover multiple components) and GUI tests. GUI tests require a running
QApplication
instance which is created by adding import tests.gui
at the top
of each test module.
Tests have been written using unittest framework. With the virtual environment activated, they can be run from the root directory of the project with:
python -m unittest discover
Potku can be packaged into a standalone executable using PyInstaller.
Make sure you have compiled potku with build
successfully and added the needed (JIBAL) data files before the packaging.
For quick deployment, run these commands in the root directory:
$ pipenv install #(if the virtual environment has not already been created)
$ pipenv shell
$ pip install pyinstaller
$ pyinstaller potku.spec
This creates a dist/potku
folder which contains the executable and all
necessary libraries.
For a more comprehensive packaging process, run the create_bundle
script in dev
.
This script compiles all external programs, installs and updates Python
dependencies, runs tests and compresses the dist/potku
folder into a .zip
archive. Run on Windows:
cd dev
pipenv run create_bundle.bat
or on other supported operating systems:
$ cd dev
$ pipenv run ./create_bundle.sh
Potku can be packaged automatically for Windows, Linux and macOS on GitHub servers by bumping its version. Running bump_version.py interactively (command line) prompts the user for a new version number. The script requires Git and GitHub CLI to use.
Entering a valid version number initiates a chain of GitHub Actions workflows to bump the version number, give master branch a new tag on GitHub and create a release to which the newly packaged Potku binaries will be uploaded. Potku follows semantic version numbering. There is more information in the automatic packaging README.
A Python script paired with a manifest of external files can be used to manage Potku's external files. The script can be used to get external files by fetching any absent and out of sync files or force downloading all files. Additionally, the script can be used to update the manifest with local out of sync files or all local files. Finally, the script can be used to create an entirely new manifest based on the external files in external/share.
Potku used to follow PEP 8. Current maximum line length is 80 in some files, but 120 in some (see issue #209 for more information).
- add typing annotations to new (and old) code. Potku didn't originally use typing annotations.
- add tests for new features and bug fixes, if possible
- try to keep GUI code separate from the backend code as much as possible (for possible use with other frontends, and for ease of testing)
- use pull requests and do code reviews
- create an issue for each pull request, and mention that issue number in the commit message (e.g. #1)
- remember to assign issues and add labels
- run tests before creating a pull request (and after merging it if the code changed in the meantime)
- manually test Potku before creating a pull request (and after merging it if the code changed in the meantime)
Some tests are timing-based. They may fail if executed too slowly or quickly.
Some tests in test_general_functions.py or test_get_espe.py may fail because of permission issues with the directory returned by tempfile.TemporaryDirectory()
. See issue #189 for more information.