Installing PyFluxPro

Installing PyFluxPro

Installing from GitHub

There are 4 steps to installing PyFluxPro from the GitHub repository:

1. Install Python.
2. Install the git version control software.
3. Clone the PyFluxPro repository using the git version control software.
4. Create a Python virtual environment for running PyFluxPro.

NOTE: A fifth step is required when installing PyFluxPro on Linux. The extra step is to build the executable files for the SOLO neural network, the MPT u* threshold detection scheme and the MDS gap filling routine, see below for details.

Installing Python

PyFluxPro is written for Python V3+ and uses a number of standard and 3rd party Python modules. OzFlux uses and recommends the Miniconda3 (https://conda.io/miniconda.html) Python V3+ distribution. This is a minimalist installation of Python which installs into your home directory and can then be automatically configured to provide all of the Python modules used by PyFluxPro.

The currently recommended way to configure the Miniconda3 installation is to create a virtual environment using "conda env create ..." using the YAML file ("environment.yml") supplied.

To install Miniconda3, follow these steps:

1. Download the Miniconda3 Python V3+ installer for your operating system from https://conda.io/miniconda.html.
2. Follow the instructions on the Conda web page (https://conda.io/docs/user-guide/install/index.html) to install the Miniconda3 Python V3+ distribution.
3. Accept all the defaults during the installation, including having Conda append the path to this Python installation to your system PATH environment variable.

At the end of this process, you should have a functioning, although minimal, installation of the Python language interpeter.

Installing "git"

The version control program git provides a convenient way to install PyFluxPro and to update PyFluxPro once it has been installed.

To install "git", follow these steps:

1. Download the git installer for your operating system from https://git-scm.com/downloads.
2. Follow the instructions on the git web page to install the git version control software.
3. Accept all the defaults during the installation.

Installing PyFluxPro using "git"

PyFluxPro is easily installed using the git version control software. This process is refered to as "cloning" the PyFluxPro repository (this web page). When PyFluxPro is installed using git then git can also be used to easily update PyFluxPro to make sure you are always using the most recent version. This is a good idea because PyFluxPro is frequently updated to fix bugs and add new features.

To install PyFluxPro using git, follow these steps:

1. Open a command line window or terminal session and use the cd (shorthand for "change directory") command to navigate to the directory into which you want to install PyFluxPro. Note that the installation process will create a subdirectory called PyFluxPro in the directory where the installation is run.
2. Clone the PyFluxPro repository by typing git clone https://github.com/ternaustralia/PyFluxPro.git at the command prompt.
3. PyFluxPro is now installed but needs a Python virtual environment to be created with the required packages before it can be used.

Creating the PyFluxPro virtual environment

Miniconda3 installs a minimal version of Python that does not include all of the packages required by PyFluxPro. The easiest way to configure the Miniconda3 installation so that it includes all of the required packages is to create a virtual environment using the environment.yml file supplied with PyFluxPro. Conda virtual environments are explained at https://conda.io/docs/user-guide/tasks/manage-environments.html. You can read the docs (always recommended!) or you can follow the steps below:

1. Open a command (or terminal) window and use cd to navigate to the PyFluxPro directory.
2. At the command prompt in the PyFluxPro directory, type conda env create -f environment.yml to create the virtual environment. This process downloads and installs the packages required by PyFluxPro which may take several minutes. The default name of the environment created is pfp_env.

Building the executable files for Linux

This step is only required if you are using PyFluxPro on Linux. The executable files are downloaded when the PyFluxPro repository is cloned under the Windows and macOS operating systems. Building the executable files for use on Linux requires the GNU Compiler Collection (gcc, C and C++) and the GNU make utility to be installed. These are usually installed by default for Linux distributions.

The build process is controlled by the make_nix shell script file in the PyFluxPro directory. To run the script file:

1. Use cd to navigate to the PyFluxPro directory.
2. Type ./make_nix at the command prompt in the PyFluxPro directory to run the script file.
3. Check that the following files exist once the script has finished;
   1. sofm, solo and seqsolo in the PyFluxPro/solo/bin directory.
   2. ustar_mp in the PyFluxPro/mpt/bin directory.
   3. gf_mds in the PyFluxPro/mds/bin directory.

Running PyFluxPro

The simplest way to run PyFluxPro is from the command line:

1. Open a command line window or terminal session and use the cd command to navigate to the PyFluxPro directory;

   1. Either;

      1. On Windows, type pfp.
      2. On Linux and macOS, type ./pfp.

   2. Or;

      1. Activate the pfp_env environment by typing conda activate pfp_env.
      2. Start PyFluxPro by typing python PyFluxPro at the command prompt in the PyFluxPro directory.

After a short time, the PyFluxPro GUI will appear. This can take a couple of minutes when the program is run for the first time. PyFluxPro should now be ready to use.

Updating PyFluxPro

PyFluxPro is still being actively developed and there are frequent changes to fix bugs and add new features. It is always a good idea to update your installation to the latest version every few days. Updating PyFluxPro is easy when the installation was done using the git version control software.

To update a PyFluxPro installation done by git, follow these steps:

1. Open a command line window or terminal session and use the cd command to navigate to the PyFluxPro directory created during the installation step above. Note that while the install is done from the directory one level above the PyFluxPro directory, the update is done from the PyFluxPro directory.
2. Type git pull origin main at the command prompt in the PyFluxPro directory. This will update the PyFluxPro installation.
3. It is a good idea to update the virtual environment when you update PyFluxPro. To do this, type conda env update -f environment.yml at the command prompt in the PyFluxPro directory. If you have difficulty with this, see https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html for instructions on removing and creating a virtual environment.

Removing PyFluxPro

Occasionally, a major, new release of PyFluxPro will require you to remove the old version and start again from scratch. Or perhaps you tried some modifications to your local installation and things got out of hand. Or maybe you just decided that PyFluxPro is the useless product of a deluded mind and simply not worth the disk space. Here is how you can remove it.

To remove a PyFluxPro installation, follow these steps:

1. Copy or move any files e.g. control files that you have created under the PyFluxPro directory to a safe location.
2. Use your favourite method, either the command line or a file manager, to delete the PyFluxPro directory. Or, simply rename the PyFluxPro directory to something else.
3. Remove the virtual environment used to run PyFluxPro. To do this, type conda remove --name pfp_env --all at the command prompt. If you have difficulty with this, see https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html for instructions on removing and creating virtual environments.