This document is currently work in progress. The source files hosted here are the latest version. If you want to see the draft report as a PDF, click here (this might not be completely up-to-date with the sources).
This document is a technical report to document the configuration and performance of the ACCESS-OM2 suite of coupled global ocean-sea ice models at 1, 0.25 and 0.1 degree horizontal resolution, intended to be a resource for the COSIMA community and readily updated. It provides additional technical detail beyond what is available in the model announcement paper (Kiss et al., 2020).
- Please sign up with GitHub and click Watch (top right corner) to be kept informed of discussions.
- To (publicly) discuss aspects of the paper, please post an issue instead of using email.
- This is a public repository, so our draft is viewable to anyone. If that bothers you, let us know here: https://github.com/aekiss/ACCESS-OM2-1-025-010deg-report/issues/4
- Figures are generated by Jupyter notebooks, viewable in GitHub or nbviewer.
Do this to download the sources for this document:
git clone https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report.git
cd ACCESS-OM2-1-025-010deg-report/
./setup.sh
./pullfigs.sh
You should then be able to generate ACCESS-OM2-1-025-010deg.pdf using latex
. You'll also need to run bibtex
to get the references and makeindex
to make the index.
pullfigs.sh
gets all the figure files but requires membership of the hh5
group - apply here. Alternatively, set the overleaf
boolean to true in the header of ACCESS-OM2-1-025-010deg.tex to make it latex-able without figures.
We are using git to manage document versions and merging. You can edit the text in one (or both!) of two ways: either Overleaf or your own LaTeX installation (see below); also see below for how to create or edit figures. This git-based workflow looks complicated but allows all contributors to work in parallel and have their changes tracked and merged together easily. At least, that's what we hope!
Alternatively (and only if you really can't stand the hassle of git) you could just download the central version as a ZIP file and email Andrew Kiss or Andy Hogg your changes. But we'd prefer contributors to use a git-based approach if possible.
Warning: Overleaf v2 is beta software. Use at your own risk.
You won't be able to see the figures when using Overleaf.
- Sign up to GitHub, go to https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report and click Fork (top right corner). This will give you your own copy of the report hosted on your GitHub page.
- Sign up to Overleaf.
- Go to https://v2.overleaf.com, choose New Project -> Import from GitHub, give Overleaf write access to your GitHub repositories (if you're OK with that), and import ACCESS-OM2-1-025-010deg-report from your fork.
- Set the "overleaf" boolean to false in the header of ACCESS-OM2-1-025-010deg.tex.
- Do your edits in https://v2.overleaf.com.
- Choose Menu -> Sync -> GitHub to push your changes back to your fork on GitHub.
- Go to your fork of ACCESS-OM2-1-025-010deg-report on GitHub and do a pull request (click Pull requests -> New pull request -> Create pull request) to have your changes be incorporated into the central version we all share.
It's a good idea to do steps 2 and 3 fairly often to keep your version in sync with the central version so that your changes can be easily merged, and everyone will have a clearer idea of what you intend for your part of the report.
- You will need LaTeX and git installed on your machine.
- Sign up to GitHub, go to https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report and click Fork (top right corner). This will give you your own copy of the report hosted on your GitHub page.
- Bring up a terminal on your machine,
cd
to a suitable directory and dogit clone https://github.com/YOUR-GIT-USERNAME/ACCESS-OM2-1-025-010deg-report.git
, inserting your git username in the obvious place. This will give you a local version of your forked repository. - Do
cd ACCESS-OM2-1-025-010deg-report; git remote add upstream https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report.git; ./setup.sh
- Get all the figure files via
./pullfigs.sh
.
Edit the document as usual.
When you want to share your changes you will need to commit them to your local repository, push this to your GitHub fork, then do a pull request to have your GitHub fork merged into the central version.
Here's how:
- Bring up a terminal and
cd
to your document directory. - Do
git status -u
to see what files you've changed (for more detail, dogit diff
). - Do
git add FILENAME
repeatedly for each file whose changes you want to commit (replacingFILENAME
with the file's relative path). Don't add any binary files (e.g. .pdf or .png). - If you added any files in step 3, do
git commit -m "My comments"
to commit these files to your local repository (with a comment on what was changed). - Do
git pull
to merge any changes from your GitHub repository into your local version (e.g. if you also pushed text changes via Overleaf or figure changes via the VDI). - Do
git pull upstream master
to merge any changes from the central version into the local version (hopefully there will be no merge conflicts). - Do
git push
to upload your repository to your fork on GitHub. This will also update the version that Overleaf sees when you sync it. - Go to your fork of ACCESS-OM2-1-025-010deg-report on GitHub and do a pull request (click Pull requests -> New pull request -> Create pull request) to have your changes be incorporated into the central version we all share.
It's a good idea to do these steps fairly often. This will keep your local version closely in sync with the central version so that your changes can be easily merged, and everyone will have a clearer idea of what you intend for your part of the report.
We would like all figures to be generated by Jupyter notebooks in the notebooks
directory to facilitate editing and updating. The Jupyter notebooks are run on the NCI VDI so they have access to the model output data.
- Sign up here if you don't have an NCI account. You need an NCI account in order to have access to the VDI. You'll also need membership of the
hh5
group to access the model output data - apply here. - Open a terminal on your local machine and download jupyter_vdi.py with
curl -O https://raw.githubusercontent.com/COSIMA/cosima-cookbook/master/scripts/jupyter_vdi.py
- Make it executable:
chmod +x jupyter_vdi.py
- Run it:
./jupyter_vdi.py
Hopefully this will open a web page (or give you a URL) showing the folders you have on the VDI (if it doesn't work, you may need to edit~/cosima_cookbook.conf
to give it your VDI username, and run./jupyter_vdi.py
again). - In this web page, click New -> Terminal to get a terminal in the VDI.
- In this web page terminal,
cd
to a suitable directory and dogit clone https://github.com/YOUR-GIT-USERNAME/ACCESS-OM2-1-025-010deg-report.git
, inserting your git username in the obvious place. This will give you a copy of your forked repository on the VDI. - Do
cd ACCESS-OM2-1-025-010deg-report; git remote add upstream https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report.git
- Set up a suitable Python environment:
module use /g/data3/hh5/public/modules; module load conda/analysis3
- Download the COSIMA Cookbook:
cd ~; git clone https://github.com/COSIMA/cosima-cookbook.git
- ...and activate it with
cd cosima-cookbook; pip install --user -e .
(If you connect to the VDI GUI directly instead of using jupyter_vdi.py, you should bring up a terminal in the VDI and do steps 5 - 10. You can open Jupyter with jupyter notebook
in the terminal.)
You are now set up to modify and run existing notebooks or create your own.
The report figures are in ACCESS-OM2-1-025-010deg-report/figures
.
Please note:
- If you make a new notebook, put it in a new subdirectory of
ACCESS-OM2-1-025-010deg-report/figures
. Each notebook should be in a separate subdirectory (i.e. exactly one notebook per subdirectory), and all its output figures should be saved in that subdirectory so we can easily tell which script generated each plot. - For LaTeX compatibility, don't use spaces or dots (other than for the final tag) in your subdirectory name, Jupyter notebook filename, or output image filenames.
- PDF is preferred for line plots. Map-type plots can be PDF or PNG. Don't use JPG.
There are a lot of useful example notebooks in the cosima-cookbook
directory.
The tutorial from the 2018 COSIMA workshop may also be useful for those new to the COSIMA Cookbook:
cosima-cookbook/DocumentedExamples/COSIMA_CookBook_Tutorial.ipynb
.
It can also be viewed here.
When you want to share your notebook changes you will need to commit them to your local repository, push this to your GitHub fork, then do a pull request to have your GitHub fork merged into the central version. You can do this by following all the steps in Workflow under To edit text via your own LaTeX installation above, but in a VDI terminal. Then share the figure files with ./pushfigs.sh
. Please don't commit output files (e.g. .pdf or .png) to git.
If you just want to incorporate your new figure files from the VDI into the version on your local machine, do ./pushfigs.sh
in a VDI terminal, then bring up a terminal on your local machine, and do ./pullfigs.sh
. But please remember to also use git to commit and share your notebook changes.
The standard git merge and diff tools don't work well with Jupyter notebooks, so it's better to install content-aware merge and diff using nbdime. Here's how:
- On the VDI, bring up a terminal (e.g. from Jupyter in your browser) and do
pip install --user nbdime
. This will install nbdime in~/.local/bin
. - Do
which nbdime
. If this shows it can't be found, you'll need to add~/.local/bin
to your path by opening~/.bash_profile
in an editor (e.g.nano ~/.bash_profile
) and addingPATH=$PATH:$HOME/.local/bin/
andexport PATH
to the end. Save the file and and exit the editor, thensource ~/.bash_profile
. - Do
nbdime config-git --enable --global
to set up git to use nbdime for diff and merge.
That's it. git will now diff and merge notebooks in a way that respects their structure. You might also want to do this on your local machine if you've cloned your fork there too.
nbdime also provides great web-based tools for comparing notebooks - see the website for details.
Many of the tables in the report (and all tables in the appendices) are automatically generated. To update them you will first need to install f90nml. Then do
cd namelists
./make_tables.py
This will take a long time the first time you run it, since it must download a large number of files. Subsequent runs will be much faster.
If you only want to update the files, not the tables, run get_namelists.sh
.