Getting Started

Creating and configuration a Python virtual environment

Note

The instructions on this page only need to be carried out once. If you have already installed the required dependencies and created a virtual environment, skip ahead to Using the Model.

Much of the following is carried out using command line. In the instructions below, “command line terminal” or “terminal” refer to any command line application for the given operating system. For Windows, this is commonly Command Prompt or Windows Powershell. These use DOS commands. For UNIX users, Git Bash is a good alternative; it is included in Git for Windows and allows UNIX commands to be used instead of DOS.

Software Installation

git

If the Git CLI is already installed, there should be a Git Bash program in your Applications. If so, open this program and verify everything is working by typing

git --version

This should display the version of git installed on the system.

Note

This should already be installed for all users on the Advanced Technology GPU machine.

If needed, download and install the Git CLI before continuing. This does not need administrative privileges to install at the user level. Confirm that it has been installed by opening a command line terminal and entering git --version.

conda

Download and install Anaconda.

Note

This is already installed on the Advanced Technology GPU machine, but it may need to be set up for each user. Keep reading to learn more.

Verify installation and configuration of Anaconda using a command line terminal:

conda --version

If Anaconda is configured properly, this should print the version of the installed software. If, instead, it returns a “command not found” error, and you know Anaconda has been installed, you most likely need to add Conda to your path variables so that your operating system knows where to find it. First, find where it was installed, and then, in Windows:

  1. In the Windows taskbar, search for “environment” and select “Edit environmental variables for your account”
  2. In the top panel of the window that opens, click the “Path” user variable, then select “Edit…”.
  3. You need to add two new paths, one at a time. Click “New” and enter the full path (starting with “C:") of the directory containing Anaconda. This may, for example, be C:\Users\user.name\AppData\Local\anaconda3, if installed at the user level (where user.name is your user name), or C:\ProgramData\anaconda3 if installed for all users.
  4. Repeat step 3 with the same path but with \Scripts\ appended to the end. For example, C:\ProgramData\anaconda3\Scripts\.
  5. Click Ok (twice) to save and exit Settings.

Close and reopen your command line terminal. Then type conda init to initialize Anaconda. Finally, try the conda --version command again. It should work now.

Clone the Repository

The model code is available on GitHub. To retrieve it:

  1. Open a terminal window and change directories (cd) to wherever you want the code to reside. For example,

    cd Documents/ageing
    Important

    Make sure the directory exists before trying to navigate into it. You cannot move into a non-existent folder.

  2. Clone the repository into the desired directory

    git clone https://github.com/MattGrossi-NOAA/FATES-BLH-ScaleAgeing .

    if you want all of the repo contents in the current directory, or

    git clone https://github.com/MattGrossi-NOAA/FATES-BLH-ScaleAgeing

    if you want the repo contents to be downloaded into a new subdirectory called FATES-BLH-ScaleAgeing. This is just personal preference. (Note the difference between the two commands is the dot . at the end.)

Create a Virtual Environment

Virtual environments are used to manage Python packages. Create a virtual environment specifically for this model. In a terminal window, navigate into the directory containing the model code (from the previous step). Then:

conda env create --name scaleageing --file=environment.yml

This command creates a virtual environment called scaleageing and downloads and installs all of the package dependencies listed in the environment.yml file contained in the repo.

Note that this virtual environment can be named anything at all, but remember what you call it – and keep it simple – because it will be invoked by name each time you use the model.

Congratulations! Now that your environment is set up – and this only needs to be done once, the first time – we are ready to start using the model.