Skip to content

Getting started

Jump to bottom
andybeet edited this page Feb 22, 2024 · 62 revisions

There are several steps to be followed to get NEUS-Atlantis up and running on your machine. If you already have Atlantis running on your machine you can skip to Running NEUS-Atlantis section

Note: In all following content assume docker = podman. They can be used interchangeably

Setup

Permissions to access code

  • Request access to Atlantis wiki and to the google-group by sending an email to [email protected]. You will be provided a user name and password to access the wiki.

  • Log in to the wiki. Print, sign, scan, and email a copy of the license to CSIRO to receive access to the code base.

  • You will be emailed a link to the code base section with instructions on how to get the latest model version or any previous revision you'd like. The code is in a subversion repository.

  • Windows users have to option to install an application (TortoiseSVN) to checkout the code. This is recommended for people not familiar with subversion. Others (including mac, linux users) will use command line svn commands. There are instruction in the wiki on how to checkout the code using either option. (Note: Try svn co -r versionNumber https://svnserv.csiro.au/svn/ext/atlantis/Atlantis/trunk if you dont want to install TortoiseSVN)

  • Permissions to access the SVN repository should use the same credentials as provided to access the wiki

  • All versions of the code contain an example folder containing files to test your Atlantis setup. We will use this example in the instructions below

Note: Setting up atlantis is slightly different depending on the platform you are using.

Docker on a windows machine

  • You will first need to install Docker Desktop on your system and create an account on Docker Hub (From which you will be pulling base images)
  • Alternatively you can install Podman (This has not been tested)

Docker/Podman on a linux or mac

  • You will first need to install Docker Desktop on your system and create an account on Docker Hub (From which you will be pulling base images)
  • Alternatively you can install Podman

Docker/Podman on a Linux server

You will need to make sure Docker or Podman is installed on an internal server. You will need permissions to access the server. Your username will also need to be added to the Docker/Podman group so you can access the daemon (Docker only). Since Docker/Podman is configured on the server no set up it required. Read Running NEUS-Atlantis

Windows desktop

As of Atlantis version 6536, it is not possible to compile the code on Windows. All efforts are now pursued via Docker/Podman.

Build the docker image

Locate the Dockerfile that is bundled with the Atlantis code and edit the file to replace the contents with:

Pre v6554

For Atlantis version prior to v6554, use this Dockerfile

FROM debian:jessie

RUN rm /etc/apt/sources.list

# Keys Expired But I ~~Want~~ Need To Hold On To The Past
RUN set -eux \
        && echo 'Acquire::Check-Valid-Until no;' >     /etc/apt/apt.conf.d/99no-check-valid-until \
    && { \
            echo "deb [trusted=yes] http://archive.debian.org/debian jessie main";\
            echo "deb [trusted=yes] http://archive.debian.org/debian-security jessie/updates main";\
    } > /etc/apt/sources.list


RUN apt-get update && apt-get install -yq build-essential autoconf libnetcdf-dev libxml2-dev libproj-dev subversion valgrind dos2unix nano

COPY .svn /app/.svn
COPY atlantis /app/atlantis

RUN cd /app/atlantis && aclocal && autoheader && autoconf && automake -a && ./configure && make && make install

WORKDIR /app/model

ENTRYPOINT ["sh"]

CMD ["RunAtlantis.sh"]

Note: debian:jessie is Debian 8 (released in 2018). This release has now been officially archived (hence the pointers to an archived location). You can also try debian:stretch (Debian 9, released in 2020) if you have build errors. For more info see release history

v6554-v6668

For Atlantis versions v6554 to v6668, use this Dockerfile. The main difference is that the base OS being pulled changed from Debian to Ubuntu

FROM ubuntu:18.04
RUN apt-get update && apt-get install -yq build-essential autoconf libnetcdf-dev libxml2-dev libproj-dev subversion valgrind dos2unix gawk nano

COPY .svn /app/.svn
COPY atlantis /app/atlantis

RUN cd /app/atlantis && aclocal && autoheader && autoconf && automake -a && ./configure && make && make install

WORKDIR /app/model

ENTRYPOINT ["sh"]

CMD ["RunAtlantis.sh"]

v6669 +

For Atlantis versions v6669 to the current version, use this Dockerfile. R is added to the build, environment variables are set, and compilation differs from earlier Dockerfile

FROM ubuntu:18.04

ENV TZ=America/New_York
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

RUN apt-get update && apt-get install -yq build-essential autoconf libnetcdf-dev libxml2-dev     libproj-dev subversion valgrind dos2unix nano r-base

COPY .svn /app/.svn
COPY atlantis /app/atlantis

RUN cd /app/atlantis && aclocal && autoheader && autoconf && automake -a && ./configure --enable-rassesslink && make && make install

WORKDIR /app/model

ENTRYPOINT ["sh"]

CMD ["RunAtlantis.sh"]

Note: The COPY command copies the .svn (hidden directory) and the atlantis directory from your machine (local or server) to the container. The path from your machine is relative to the directory in which the Dockerfile is located. For example:

COPY atlantisCode/atlantis /app/atlantis will copy the source code from the folder atlantisCode/atlantis on your machine to the /app/atlantis folder inside the container

  • Build the docker image. From within the directory containing the Dockerfile, type

    docker build -t atlantis:example .

Don't forget to type the period!

This will take 10-15 mins to build the image. An image will be built with the name atlantis:example (Note: the -t flag is used to give the image a name)

Run the docker image

> docker run --mount "type=bind,src=/full_path_to_example,dst=/app/model" atlantis:example

This will mount the model input files (prm, bgn, csvs etc) to the app/model directory in the container. The model will run and the output will be exported to the folder name defined in the RunAtlantis.sh shell script. This output folder will be created inside the example folder

Note:There can be no whitespace in the --mount string

  • Contents of RunAtlantis.sh script will look something like this for the example (prior to version v6627)

    #!/bin/bash

    find /app/model -type f | xargs dos2unix

    atlantisMerged -i INIT_VMPA_Jan2015.nc 0 -o outputSETAS.nc -r VMPA_setas_run_fishing_F_Trunk.prm -f VMPA_setas_force_fish_Trunk.prm -p VMPA_setas_physics.prm -b VMPA_setas_biol_fishing_Trunk.prm -h VMPA_setas_harvest_F_Trunk.prm -s SETasGroupsDem.csv -q SETasFisheries.csv -d output

  • And something like this from v6627 (a migration input file was added)

    #!/bin/bash

    find /app/model -type f | xargs dos2unix

    atlantisMerged -i INIT_VMPA_Jan2015.nc 0 -o outputSETAS.nc -r VMPA_setas_run_fishing_F_Trunk.prm -f VMPA_setas_force_fish_Trunk.prm -p VMPA_setas_physics.prm -b VMPA_setas_biol_fishing_Trunk.prm -m SETas_Migrations.csv -h VMPA_setas_harvest_F_Trunk.prm -s SETasGroupsDem.csv -q SETasFisheries.csv -d output

The first line is required to allow for execution of the commands that follow. The second line deals with line ending issues. It converts all windows line endings (files found in the app/model folder) to linux format.

The third line runs the Atlantis model. The output folder is specified after the -d flag. In this case it is called output. The other file names (.prm, .csv, .nc) are all input files that can be found in the example folder

Legacy workflow (Windows)

Note: This approach should be avoided.

You will first need to install

  • Visual Studio C++ 2010 Express Edition
  • NetCDF4 (+DAP) which includes dependencies

both of which can be found on the atlantis wiki.

To build the source code

  • Open the atlantis_VS2010.sln file in Visual Studio C++ 2010
  • Right click on "solution atlantis_VS2020"
  • Select "Build solution" or hit F7

The build process should show all projects succeeding and 0 failing. If you see errors please visit the wiki. There are a list of common build errors with fixes. Once the build process is a success:

  • Copy the atlantismain executable (atlantismain.exe) from atlantismain/atlantis/Debug to the example folder
  • Open up windows powershell
  • Navigate to example directory
  • Enter the following:

./atlantismain -i INIT_VMPA_Jan2015.nc 0 -o outputSETAS.nc -r VMPA_setas_run_fishing_F_Trunk.prm -f VMPA_setas_force_fish_Trunk.prm -p VMPA_setas_physics.prm -b VMPA_setas_biol_fishing_Trunk.prm -h VMPA_setas_harvest_F_Trunk.prm -s SETasGroupsDem.csv -q SETasFisheries.csv -d out

  • The example model should run and output will be saved in example\out

Running Atlantis

Calibration

Model Components

Model Criteria

Documentation

Clone this wiki locally