Installing PyFluxPro - OzFlux/PyFluxPro GitHub Wiki

There are 2 ways to install PyFluxPro:

1. Using the single file installers available from https://github.com/OzFlux/Installers.git.
2. Installing directly from the PyFluxPro repository on GitHub, see https://github.com/OzFlux/PyFluxPro.git.

Installation using the single file installers is only available for Windows and macOS. If you're using Linux then you'll have to install from the GitHub repository.

There are advantages and disadvantages to both methods of installing:

1. Single file installers;
   1. Advantages;
      1. Convenient, no need to install any other software.
   2. Disadvantages;
      1. May have problems installing on macOS due to its security policy.
      2. May not be the latest version.
      3. You can't hack it to make it do what you want.
2. GitHub repository;
   1. Advantages;
      1. May avoid security issues especially on macOS.
      2. Always gets the latest version and is easy to update.
      3. You can hack it to do what you want.
   2. Disadvantages;
      1. Requires installation of Python and git.

The single file installers are available from https://github.com/OzFlux/Installers.git.

You can download the installer by following these steps:

1. Click on the folder for your operating system.
2. Click on the installer file. Choose the file with the highest version number to get the latest version.
3. Click on the Download button at the right hand edge of the screen.
4. The file will start downloading after a delay of several seconds.

Follow these steps to install PyFluxPro:

1. Navigate to the folder containing the downloaded installer, this will usually be your local Downloads folder.
2. Run the installer by double clicking on the installer file.
3. Accept the defaults.

Note that if your computer is administered by an IT section, you may not be able to install PyFluxPro because you don't have full administrator privileges. Contact your local, friendly IT people for help.

Follow these steps to install PyFluxPro:

1. Navigate to the folder containing the downloaded installer, this will usually be your local Downloads folder.
2. Uncompress the ZIP file by double clicking on the installer file. Note that some configurations of macOS will do this automatically when the file is downloaded.
3. Uncompressing the ZIP file will create a folder called PyFluxPro, move that folder to where you PyFluxPro e.g. Users/<username>/PyFluxPro.
4. The first time you try to run PyFluxPro, macOS may refuse to allow it to start because macOS has been unable to check PyFluxPro for malicious software. If this happens, go to System Preferences, select Security & Privacy and under the General tab there should be a message about Python. Click the Allow anyway button to allow PyFluxPro to run. NOTE: Starting with Monterey, macOS will not run programs unless they have been notarised. If you keep getting error messages when you try and run PyFluxPro then this is the likely cause. There is a work around for this problem which we can discuss at the workshop.

Note that if your computer is administered by an IT section, you may not be able to install PyFluxPro because you don't have full administrator privileges. Contact your local, friendly IT people for help.

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.

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.

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.

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

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.

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/OzFlux/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.

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.

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.

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.

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.

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.