Getting Started
This section will guide you through the steps needed to get ecFlow up and running on your environment. ecFlow is available on several platforms such as Linux and MacOS, including HPC environments as the one available at ECMWF.
The instructions below will help you to get started on your individual machine, a shared machine or the ECMWF HPC.
An individual machine is a machine that is used by a single user, and typically where the user has full control of the environment.
In an individual machine, an ecflow_server can be started by simply calling the following command at the unix prompt:
ecflow_server
This will launch the server in the foreground, which can be stopped by typing Ctrl-C. To enable a verbose output, use the -d option, as follows:
ecflow_server -d
This command will start an ecflow_server running on your system with a default host name of localhost and port number 3141.
Warning
If another program on the machine is already using the same port number, then an “Address in use” error will be reported and the server will not start.
To start the server on a specific port number you can either specify the --port option or define the ECF_PORT environment
variable, as follows:
# using --port option
ecflow_server --port 3500
# using ECF_PORT environment variable
export ECF_PORT=3500; ecflow_server
While the above is the simplest way to start ecflow_server, the preferred way to start an ecflow_server is to use the script
ecflow_start.sh, as this script prevents unintentional shared usage of the server by automatically selecting a port number
unique to your user ID.
A machine can be shared by multiple users, and multiple ecFlow servers can be executed in parallel.
To launch an ecflow_server on a shared machine, consider using the ecflow_start.sh startup script as it will automatically
run on a port number unique to the user ID.
By default, this script defines the ecflow_server working directory as $HOME/ecflow_server, where the log and
check point files are stored. The ecflow_server working directory can be customised using the -d option, as follows:
ecflow_start.sh -d /alternative/working/directory/for/ecflow_server
Note
Please take note of the host and port reported by ecf_start.sh.
The host and port number uniquely identify the ecflow_server, and will be needed to access the server when using ecflow_client, Python API or ecflow_ui.
Warning
The execution of ecflow_server directly on the ECMWF HPC environment is strongly discouraged.
Users are instead recommended to request a dedicated ecFlow virtual machine (VM) and run their own Single/Shared machine.
In the ECMWF HPC environment, the ecFlow executables are made available by the module command.
Run the following commands to load Python 3 and ecFlow:
module load python3
module load ecflow/new
As in a Single or Shared machine, an ecflow_server can be started by running the following command at the unix prompt:
ecflow_server
Regardless of the selected way to run the ecflow_server, the log files and check point files are by default created in the working
directory, and will have the prefix <machine_name>.<port_number>. This naming schema avoids overwriting information when multiple servers are,
for example, run on different ports.
When relaunching an ecflow_server, the server will attempt to automatically reload the suite definition from the check point file.
What to do
Ensure that ecFlow is installed and accessible on your system. Run the following command to check that ecFlow is installed:
ecflow_server --version ecflow_client --version
Setup the Tutorial directory, and start the ecflow_server using:
mkdir $HOME/course cd $HOME/course ecflow_server -d # n.b. the server runs in the foreground, on port 3141 -- use Ctrl-C to stop it
Check if the server is running by using the command:
ecflow_client --ping