Personal OMFIT installation

Running a personal OMFIT installation requires having access to the OMFIT source code, and having a Python environment properly setup.

Get access to the OMFIT source code

  1. Obtain a GitHub account and set it up so that you can clone the OMFIT repository.

  2. Fill out the OMFIT users agreement form (fill in your GitHub username to be added to the OMFIT repository on GitHub)

  3. After receiving access to the GitHub repository, clone the unstable branch on your host with:

    git clone -b unstable git@github.com:gafusion/OMFIT-source.git
git submodule init
git submodule update --recursive

Setup the OMFIT Python environment

Support for Python 2.7 has been dropped, and all new installations must be carried out with Python 3.6+.

We recommend the following strategies to setup your OMFIT Python environment:

  1. Linux: Anaconda package manager

  2. OSX: Anaconda package manager (or Macports with lesser support)

  3. Windows: Windows Subsystem for Linux with the Anaconda package manager

  4. RaspberryPi: OMFIT has been installed on a Raspberry Pi 4 via pip requirements

  5. Docker: the OMFIT Docker image will run wherever Docker can be installed

Users who wish not to use one of the methods listed above can refer to this list of required and optional packages.

Setup the OMFIT classes

OMFIT classes can be installed and used standalone, for example in your (i)Python or jupyter notebooks. To install them:

pip install --upgrade omfit_classes

Run the OMFIT framework

Depending on the installation environment of OMFIT, different commands are used to start the framework and and initialize SSH_AGENT password forwarding.

miniconda:

OMFIT-source/bin/omfit_conda_3.sh

MACports:

OMFIT-source/bin/omfit_macports_3.sh

Docker:

There are several scripts available to run omfit in a docker environment depending on the installed OS.

OMFIT-source/bin/omfit_docker_linux.sh

or

OMFIT-source/bin/omfit_docker_osx.sh

or

OMFIT-source/bin/omfit_docker_windows.bat

Note: Most of the scripts use the omfit_launch.sh script to launch omfit after the specific environment has been set up.

Manual Installation:

If OMFIT has been installed manually using pip installation of the required (and possibly optional packages) then use the following command to run the OMFIT framework.

python3 OMFIT-source/omfit/omfit.py

For first time users:

In order to update a value entered into a data field in OMFIT, the user must hit the enter key to save the value. If a field is highlighted green, the value has been changed but has not yet been updated.

When OMFIT first starts it will open a window where preferences can be set. An email address is required and the window can not be closed if the email field has not been updated. The email address is entered into this field surrounded by single quotes followed by pressing the enter key to update the value. (If the field is highlighted green the value has not been updated). After all the desired preferences have been entered, use the Save button to store these preferences.

Running a personal copy at an institution where OMFIT is already available

To run your own personal copy where a public installation of OMFIT is already available does not require your own installation of Python! For example on iris, at GA, this can be done by:

module load omfit/unstable     # load the OMFIT Python environment of your choice
cd path_to_my_OMFIT-source     # go to OMFIT-source directory that holds the OMFIT installation you want to run
omfit --cwd                    # start OMFIT with Python environment of your choice and OMFIT from the Current Working Directory

This will use the Python environment of the public omfit command, but the installation of OMFIT from the Current Working Directory.

Institutional OMFIT installation

Institutional installations are typically done through the AToM environment which is used to manage both the OMFIT framework installation, its environment, as well as other AToM components.

The GDT (Global Deployment Tool) module in OMFIT should be used to keep track of multiple miniconda environments and OMFIT installations All these will be installed under a single atom folder, based on the AToM repo. The system uses clear folder names for each version of OMFIT and the miniconda environments. There is also an option to keep all older version of the OMFIT master branch around, as well as all of the old miniconda environments. This feature can be used to make sure people can go back in time with the exact same environment that they used in the past.

The steps required to move forward are as follows:

  1. Start your personal version of OMFIT

  2. import the GDT module

  3. Update/add the settings for your institution under

    • OMFIT[‘GDT’][‘SETTINGS’][‘INSTALLATION’][‘ATOM’][__SERVER_NAME_GOES_HERE__][‘origin/master’]

    and under:

    • OMFIT[‘GDT’][‘SETTINGS’][‘INSTALLATION’][‘OMFIT’][__SERVER_NAME_GOES_HERE__][‘origin/unstable’]

    making sure to add your username as owner.

    NOTE:

    • the ATOM GDT run once a day and take care of keeping the Python environment and the OMFIT-source_master and OMFIT-source_unstable folders up to date.

    • the OMFIT GDT runs every 10 mins, and will keep OMFIT-source_unstable up to date more frequently.

  1. Run the GDT GUI, and click on:

    • Check GitHub for updates under the ATOM –> overview tab.

    • CLONE button under the ATOM –> SERVER_NAME tab. This will clone the atom repo where you told it to. You’ll need to do this only once.

    • PULL button under the ATOM –> SERVER_NAME tab. This will actually install miniconda and the OMFIT-source_master and OMFIT-source_unstable folders. This will take some time.

  2. Make sure that the everything gets installed as you’d like it to be.

  3. Export your changes and commit them to the OMFIT-source repo, so that these changes are updated on GitHub.

  4. To keep your installations up to date, load the GDT, and run the Loop every 600 seconds to keep my installations up-to-date. OMFIT-source_unstable will update every 10 mins, but OMFIT-source_master and the environment will only be updated every day. Or at least, this is the default setting.

  5. Once you are at this stage, we can then modify the module load omfit and related to point to your new installations.

  6. Document installation: Let people know how to run your public OMFIT installation by adding the documentation to the OMFIT-source/docs/source/installations folder.