FMU Hub

Getting started with FMU

This is a guide to get you started with FMU as quickly and smoothly as possible.

Rule number 1: Never work alone.

Getting started with FMU is an activity that is best done in a team or at the very least together with a colleague. If you find yourself in a situation where you are trying to figure this out on your own, this will be your first problem to solve.

FMU is backed by a large and collaborative community of helpful, skilled people. You will find help in several open channels on Slack or on FMU Users on Viva Engage. There are also courses and tutorials available.

Lets get started! 🚀 These are the steps:

1. Obtain the necessary accesses and pre-requisites

2. Configure your Linux profile for using the Equinor HPC environment

3. Know the basics of how to work on Linux

4. Verify by running an FMU workflow once

1. Accesses and pre-requisites

In this section, you will get the necessary accesses and pre-requisites to be able to run FMU workflows on Equinor Linux.

1.1 Apply for the following accesses/applications:

Basic Unix

TGX Receiver Windows

Access to relevant Linux area

If you are participating on an instructor-led FMU course, or if you are following the FMU tutorial, please apply for access to /scratch/fmu - fmu_scratch (Stavanger). Otherwise, apply for access to the project area you will be working in.

Example of a project area: /project/johan_sverdrup.

1.2 Log on to Equinor Linux

Install the latest version of TGX Receiver from the Company Portal.
Go to the (RGS/TGX portal). Select "Stavanger", find the "Default" machine type and click "New session".
A file called "leostream.tgx" will be downloaded. Find and open this file. It will automatically open in TGX Receiver.
Select which monitors you would like to use (one, or all), and click "Connect". You may need to click "Add Exception" in a dialogue box, if this is the first time you connect to this node.
Log in with your Equinor credentials.
When the Linux desktop opens, you need to (once again) log in with your Equinor credentials.

A couple of TGX usability hints:

When getting a black window during the login process, just click with mouse pointer inside the window and hit [space].
When "Linux Windows Desktop" is opening, right-click and drag the upper-left "map window" in a better position to see the menu hidden behind it.

Congratulations, you are now ready to start using Linux in Equinor 🎉

2. Know the basics of working on Linux

In this section, you will aquire some super basic Linux skills. Enough to get you started, but by no means a detailed introduction to Linux.

While the Linux environment is well known to many subsurface professionals, many have never worked outside Windows (or Mac). Therefore, it is important that you know that since the majority of FMU is running on Linux, basic knowledge and understanding of Linux is necessary.

If Linux is not known to you, we recommend that you spend some time getting aquinted with it. You will quickly find that while Linux is quite different from e.g. Windows in some respects, mastering it to a certain level will dramatically improve your efficiency and productivity.

A good place to start is the internal basic-level introduction course:

[SUB] Linux for Subsurface in Equinor - Basics.

It covers the basics of Linux, and it is a good starting point for further learning.

2.1 Open a terminal window

Open a new terminal window either via the Linux menu, or using the Ctrl+T keyboard shortcut.

The terminal is your command line interface to Linux. Here you will type commands to navigate the file system, open applications, run scripts and programs etc. These are some basic commands to get you started:

Command	Description
ls	List files and folders in the current folder
cd <foldername>	Change directory to the folder called <foldername>
cd ..	Go up one level in the folder structure
cd ~	Go to your home folder
pwd	Print working directory (show which folder you are currently in)
mkdir <foldername>	Make a new folder called <foldername>
rm <filename>	Remove (delete) the file called <filename>
rmdir <foldername>	Remove (delete) the folder called <foldername>

Linux is a widely used operating system, and there are many resources available online as well.

2.2 Open Visual Studio Code

On Equinor Linux, several text editors are available. Editors is a constant topic of debate, and there are many opinions on which editor you should choose. The right editor for your colleague may not be the right editor for you! For a smooth start we recommend that you use Visual Studio Code.

In the terminal, open Visual Studio Code using the code command

You can also open a specific file with VS Code by using the command code <filename>, and you can open a specific folder by using the command code <path/to/folder>.

(The command code . will open the folder you are currently in).

We recommend VS Code because it is widely used in the FMU community. If you feel comfortable with other editors, you can of course use them. Getting started will be exponentially more difficult for you if you are using a complicated text editor from the start.

FMU-specific syntax highlighting (ERT) is available for VS Code. Follow (this link) on Linux for information and installation. Kudos to Thorbjørn Horgen 👏

3. Configure your Linux profile for using the Equinor HPC environment

In this section, you will do some basic configuration of your Linux profile to enable you to run FMU workflows on the Equinor HPC environment.

Komodo is our software distribution system for Python packages. At any point in time, multiple different teams and individuals are writing code and making it available to everyone. To avoid the utter chaos that would quickly ensue if everyone could deploy anything at any point in time, deployments are funneled through the (monthly) Komodo release cycle. While developers make sure their code is deployed through Komodo, you need to make sure that your Linux profile actually picks up these packages from Komodo, or in other words: You need to source Komodo.

Your Linux profile setup is stored in text configuration files, that you will find in the folder called /private/<your_user_name>/. Depending on which shell you are using, the file name and its format will look slightly different.

Unix comes with several different shells; the command-line interpreter program that parses the commands you write and sends them to the operating system.

In Equinor, two primary shells are used: C Shell and Bourne Again Shell (bash).

If you do not know which shell you are using, you are most likely using C-shell. You can verify which shell you are using by typing this command:
echo $shell in a terminal window. You can also (change your default shell)

3.1 Find and open your *rc file

Depending on which shell you are using, find and open your respective *rc file:

Shell	Configuration file
C Shell	/private/<MyUserName>/.cshrc
Bash	/private/<MyUserName>/.bashrc

Every time you open a terminal window, this file is read and the commands inside it are executed.

Open the *rc file using your chosen text editor, example for C-shell users using VS Studio Code:

cd /private/<MyUserName>/

code .cshrc

Many users customize their environment, and at some point you will too. But for a smooth start we strongly recommend that you start with a basic setup that works.

Be very careful copying settings from other users. We see again and again that newly onboarded users receive faulty setups from existing users. While it may seem like a quick fix to simply copy settings from someone else, it may also cause you problems.

3.2 Add configuration to your *rc file

You will add two (2) lines to your *rc file. The first line will source Komodo, and the second line will source an extra configuration for Eclipse.

Shell	Configuration file	Line to insert
C Shell	.cshrc	source /prog/res/komodo/stable/enable.csh source /prog/res/ecl/script/eclrun.cshrc
Bash	.bashrc	source /prog/res/komodo/stable/enable source /prog/res/ecl/script/eclrun.bash

These lines should be added before the line that looks approximately like this:

if ( $?prompt == 0 || $?VUE != 0 ) exit

.cshrc example (C-Shell):

# enable komodo

source /prog/res/komodo/stable/enable.csh

# this is for eclrun and slbrun to work - includes the site specific license settings to be used

source /prog/res/ecl/script/eclrun.cshrc

# you may or may not have the following line

if ( $?prompt == 0 || $?VUE != 0 ) exit

.bashrc example (Bash):

# enable komodo

source /prog/res/komodo/stable/enable

# this is for eclrun and slbrun to work - includes the site specific license settings to be used

source /prog/res/ecl/script/eclrun.bash

# you may or may not have the following line

if ( $?prompt == 0 || $?VUE != 0 ) exit

Some old setups still have this line present:

source /project/res/SDP_cshrc

If you find this line in your setup, remove it. It should not be there, and it will cause problems.

When your *rc file has been modified and saved, you can open a new terminal window to see the changes. In the new terminal window, you can verify that Komodo is sourced by typing:

echo $KOMODO_RELEASE

This should return the version of Komodo you are currently sourcing. If nothing is returned, go back and verify the changes you made to your *rc file. Otherwise, proceed!

A new version of Komodo comes every month, and there may be upgrades to packages distributed with Komodo that are important to FMU users (new features, bug fixes, security updates etc). You can monitor the changes via the Komodo release notes.

If you are currently participating in the FMU introduction course, you can now return to the course documentation and follow the instructions given there.

3.3 Equinor-Rio only: Setup of password-less ssh login

FMU users in Rio need to setup password-less ssh login by running the following command in a terminal window:

/prog/util/scripts/setup-ssh-keylogin

4. Verify by running an FMU workflow once

In the final step, you will verify that everything is working by running an FMU workflow once.

We will not go into detail on this here, as this varies from location to location. We assume you are following rule number 1 and that you are doing this together with a colleague or a mentor. Ask them to help you getting access to a workflow that you can run, and they will teach you how to 1) set a new case name, 2) launch the ERT application and 3) launch a run.

Tell them that you would like to run your testrun on the cluster (not locally on RGS) (do not choose "Single realization test run in ERT) so that you can verify that all the stuff you have done is working.

Now the real learning can begin. Connect with the FMU community, have a look at the available courses and tutorials if you haven't done so already.

Welcome to FMU, welcome to the community and remember to never work alone! 🥳