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
    

Setup the OMFIT Python environment

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

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

  1. Linux: Anaconda package manager

  2. OSX: Macports package manager (or Anaconda package manager 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.

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.

  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, being sure to add your GitHub username there, to be added to the OMFIT repository on GitHub

  3. Clone the public AToM repository:

    git clone git@github.com:scidac/atom.git
    
  4. Let the AToM makefile retrieve and install OMFIT and its CONDA environment:

    cd atom
    make OMFIT  # install/update OMFIT
    make CONDA3 # install/update OMFIT CONDA environment (only does something if new OMFIT environment is available)
    
  5. Customize institutional installation: The default user settings for an institution can be set by editing the OMFIT-source/institutions/institution.___ file, which overrides the default entries in OMFIT['MainSettings'] with institution-specific settings. Auto-detection of the institution is based on existence and writability of the stats_file.

  6. Mark this installation as “public”, which will prevent you (the maintainer of this installation or others with write access) from accidentally exporting modules and editing files in developer mode on this installation. Add an empty file named public under the OMFIT-source folder.

  7. Keep installation up-to-date: OMFIT is powered by a vibrant community, and several tens of commits per day are not uncommon. With tens of OMFIT public installations scattered around the globe, it is a challenge to keep them up-to-date. The OMFIT Global Deployment Tool (GDT) is a module in OMFIT tasked with maintaining all OMFIT public installation and environments synchronized and up-to-date.

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

  9. Start OMFIT:

    atom/OMFIT-source/bin/omfit