Guide for new team members


Welcome to our research group! This page provides some information that will help you get started on your research. The first part is a technical guide that describes how to install ISSM, how to connect to various servers, and how to back up your work. The second part outlines our vision for our group culture and ethics. Feel free to reach out if you have questions or if you find mistakes.

Ice Sheet Modeling reference


My PhD thesis has lots of mistakes, but provides a good background in ice sheet modeling. It is available here. I also recommend the lecture notes of Hilmar Gudmundsson available here.

Software


Apple/Xcode

If you have a Mac (recommended), you will need Xcode. If it is not installed already on your machine, open the App Store and download Xcode. You will need it to compile the code among other things.

You will also need to download and install XQuartz in order to be able to plot figures on totten.

Windows

If you have a windows machine (not recommended…) you will need to download MobaXterm to work on Totten, or other linux servers. Download and install MobaXterm and select Get/Free edition/installer. Follow the instillation wizard and open MobaXterm. Start local terminal. From here you can ssh into Totten. Input:

ssh -Y yourlogin@totten.dartmouth.edu

gfortran

You will have to install one. GFortran Binaries are available here. Select the version of gfortran that is compatible with your OS (If you are not sure, click on the apple in the upper left corner, and select “About this Mac”).

Terminal (iTerm2)

You need to use iTerm2 for your terminal (it is much better than Apple’s terminal: it copies on selection, you can blur the background, etc). I suggest the following settings (iTerm2/Preferences):

  • General/Selection: add colon (:) in the list of “Characters considered part of a word for selection”, it will be handy when you debug C++ and MATLAB code using vim
  • Appearance/Tabs: check “Show tab number”
  • Profiles/Colors: set the Cursor color as red and do not check “Smart cursor color”, Set the Foreground color to white and Background color to black
  • Profiles/Text: change the font to 14pt Monaco
  • Profiles/Window: set Transparency to 30%, check Blur and set it to 30%. In “Settings for new Windows”, select 166 Columns and 55 Rows (that will make your initial terminal bigger)
  • Profiles/Terminal: Check “Silent bell”

LaTeX

I expect you to be familiar with LaTeX to write reports/papers/thesis basically anything. You can download LaTeX for mac here and also set up an overleaf account (free Pro account with your Dartmouth email). If you are not familiar with LaTeX, there is a great wikibook available here: https://en.wikibooks.org/wiki/LaTeX, start with the section “Basics”.

MATLAB

Dartmouth provides free MATLAB licenses to Dartmouth students/staff/faculty. Carefully follow the instructions and download the latest version of MATLAB.

ISSM


You can “checkout” ISSM from source (using trunk-jpl if you have access). If you do not have access to trunk-jpl, you can download ISSM using the anonymous login:

 svn --username anon --password anon checkout https://issm.ess.uci.edu/svn/issm/issm/trunk 

if you do have access to trunk-jpl and have a password associated to your login name, you can download the development branch instead as follows:

 svn --username USERNAME checkout https://issm.ess.uci.edu/svn/issm/issm/trunk-jpl 

replace USERNAME by your ISSM username. svn will ask you for your password, and you will then be able to download the code. Don’t install ISSM at this point, we need to make changes to your environment first.

Environment


bash/zsh

You will use the BASH or ZSH shell, here is a quick introduction if you have never used BASH before http://www.panix.com/~elflord/unix/bash-tute.html

options to your ~/.zshrc (change to your needs):

#Prompt
PROMPT='%(?.%F{green}√%f.%F{red}?%?%f)%B%F{203}%m%b%f:%B%F{83}%1~%b%f%F{226}$%f '

#File/directory colors
export LSCOLORS="dxgxfxfxcxdxdxcxcxfxfx"
alias ls="ls -G"

#SVN options (you should use vim of course!)
export SVN_EDITOR="/usr/bin/vim"

#GREP options
export GREP_COLOR='00;44'
alias grep='grep --binary-files=without-match '

#Useful aliases
alias fxg='find ./ -type f | egrep -v "\.svn|Makefile|\.deps\/" | xargs grep -n --color=auto '
alias ss='svn status -u'
alias vv='svnvimdiff '
alias mkc='HERE=`pwd` && cd $ISSM_DIR/src/c && make -j 4 install && cd $HERE' 

#ISSM
export ISSM_DIR= PUT YOUR PATH TO ISSM DIR HERE (example: "/Users/mmorligh/Desktop/issmuci/trunk-jpl")
source $ISSM_DIR/etc/environment.sh

#ISSM aliases
alias cdi=' cd $ISSM_DIR'
alias cdm=' cd $ISSM_DIR/src/m'
alias cdu=' cd $ISSM_DIR/src/m/utils'
alias cdmc='cd $ISSM_DIR/src/m/classes'
alias cdc=' cd $ISSM_DIR/src/c'
alias cdo=' cd $ISSM_DIR/src/c/classes'
alias cdx=' cd $ISSM_DIR/src/wrappers'
alias cdt=' cd $ISSM_DIR/test/NightlyRun'
alias ma='/Applications/MATLAB_R2021b.app/bin/matlab -nodesktop -nosplash -r "addpath $ISSM_DIR/src/m/dev; devpath;"'

On a linux server, you will instead edit your ~/.bashrc and change the first 6 lines to:

#Prompt
export PROMPT_COMMAND='echo -ne "\033]0;${HOSTNAME}\007"'
export PS1=$(echo -ne "\[\033[1;31m\]\h\[\033[00m\]\[\e[0m\]:\[\033[01;32m\]\W\[\033[00m\]\\[\033[01;33m\]\$\[\033[00m\] ")

#File/directory colors
export LS_COLORS="no=00;37:fi=00;37:di=00;33:ln=00;36:pi=40;33:so=00;35:bd=40;33;01:cd=40;33;01:or=01;05;37;41:mi=01;05;37;41:ow=00;35:ex=08;32:*.cmd=01;32:*.exe=01;32:*.mexa64=01;32:*.mexmaci=01;32:"
alias ls='ls --color=auto'

#This alias works on Totten
alias ma='LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6  /usr/local/MATLAB/R2021b/bin/matlab -nodesktop -nosplash -r "addpath $ISSM_DIR/src/m/dev; devpath;"'

replace the path to MALTAB (last line) and ISSM_DIR by the ones of your machine. Once you are done, you can close the terminal and reopen it. If you do:

 echo $ISSM_DIR 

you should see the absolute path to trunk (or trunk-jpl). If not, make sure to edit your~/.zshrc (or ~/.bashrc or ~/.bash_profile). You can also do:

 ls $ISSM_DIR 

it should show you the list of files and directories in trunk. If it complains “No such file or directory”, the path that you entered in your ~/.bashrc is wrong. Correct it and open a new Terminal.

VIM


the only editor that you will use is VIM. You do not need to download and install vim, it is installed by default. You will use vim to code, but also to write papers and proposals. You will see that ISSM has been written for vim users (we use folds to navigate easily within files that have several thousands of lines for example). We first need to customize vim for ISSM:

cd ~
ln -s $ISSM_DIR/externalpackages/vim/addons/vim .vim
ln -s $ISSM_DIR/externalpackages/vim/addons/vimrc .vimrc

You can then do the vim tutorial if you have never used it before:

 vimtutor 

The only commands that this tutorial does not teach you are “zo” to open a fold and “zc” to close a fold.

Installing ISSM


You are now ready to install ISSM. Standard instructions are provided here: http://issm.jpl.nasa.gov/download/unix/ (you will NOT need python), and you will also find specific instructions for some of our machines (like totten) here: https://issm.ess.uci.edu/trac/issm.

Running ISSM


Once you are ready, you can type ma in a Terminal, it will launch MATLAB and load ISSM’s tools (see the ma alias in your ~/.bashrc). You should see something like:

 ISSM development path correctly loaded 

You can then type issmversion in MATLAB, you should see the following message:

>> issmversion

Ice Sheet System Model (ISSM) Version 4.11
(website: http://issm.jpl.nasa.gov contact: issm@jpl.nasa.gov)

Build date: Thu Aug 25 09:36:19 PDT 2016
Compiled on apple darwin15.6.0 x86_64 by mmorligh

Copyright (c) 2009-2016 California Institute of Technology

 to get started type: issmdoc
If you see an error message similar to this one:
Invalid MEX-file '/Users/rtwalker/ISSM/trunk/lib/IssmConfig.mexmaci64':
dlopen(/Users/rtwalker/ISSM/trunk/lib/IssmConfig.mexmaci64, 6): Symbol not found:
__gfortran_transfer_array_write

Follow the instructions here: http://issm.jpl.nasa.gov/documentation/faq/matlab/ (second paragraph). You can then work on the ISSM tutorials to familiarize yourself with ISSM.

JPL SVN and projects


You may have access to another SVN repository that we call the JPL svn for projects. If you do, do not checkout the entire repository, it is too big. You can check out the following:

svn co --username USERNAME --depth=empty https://issm-svn.jpl.nasa.gov/svn/issm/issm issmjpl
cd issmjpl
#if you want to download the publications directory and references.bib
svn update publications
#if you want to edit the website
svn update --depth=empty website
cd website
svn update html_content

ke sure to create your project directory (e.g., proj-morlighem in issmjpl), and never commit data or models. Only matlab scripts, exp files, and anything else you would need to recreate your models. Commit as you can so that it is properly revisioned.

SVN and coding guidelines


You will find on Trac some instructions about svn (that you should be familiar with), and general coding rules.

rclone (backup your work on totten)


As you know, with your Dartmouth affiliation, you have unlimited storage on Google Drive (yep! That’s right!). rclone is a software package installed on totten.dartmouth.edu that lets you automatically copy a folder of totten to your Google Drive so that, if anything happens (yes it has happened…), your work is still in the cloud and can be recovered.

You can configure rclone on totten using these instructions:

 rclone config 

  • Create a new remote (e.g., gdrive_mathieu)
  • Select “Google Drive” (option 13)
  • Leave blank the following 2 questions (client_id and client_secret)
  • Scope: Full access all files (option 1)
  • Leave blank the following 2 questions (root_folder_id and root_folder_id)
  • Edit advanced config: No
  • auto config: No
  • Then firefox should open and ask you to log in using your Dartmouth Google account (on Totten it may be faster to copy and paste the link on your local browser and follow the instructions)
  • Configure this as a team drive: No

You should then copy manually the directory you want to save on your Google Drive account. I recommend only saving your project directory. Here is the command that worked for me on totten:

 rclone -v --transfers=32 --checkers=16 --skip-links --drive-chunk-size=16384k --drive-upload-cutoff=16384k copy /home/morlighe/issmjpl/proj-morlighem gdrive_mathieu:proj-morlighem 

So, you see that there are a bunch of options but in the end, I am asking rclone to copy the directory /home/morlighe/issmjpl/proj-morlighem that is on totten, to my Google Drive directory called gdrive_mathieu:proj-morlighem (name of your Google drive account when you configured rclone, followed by a colon and the directory name in my Google Drive folder). You may want to try with a smaller folder first to make sure it works (once the rclone command is done, open a browser and check your Google Drive). Once everything is copied and you are happy with it, you can automate a backup, say once a week using a cronjob. Create a file on totten called cronfile and put the following lines:

#use /bin/bash to run commands, overriding the default set by cron
SHELL=/bin/bash
 
#mail output to you
MAILTO=mathieu.morlighem@dartmouth.edu
 
#update PATH
PATH=/usr/local/bin:/bin:/usr/bin:~/bin
 
#cronjob (every Sunday at 1pm)
00 13 * * 0 rclone -v --transfers=32 --checkers=16 --skip-links --drive-upload-cutoff=16384k  copy /totten_1/mmorligh/issmjpl/proj-morlighem gdrive_mathieu:Totten-proj-morlighem

the important command is the last line. It is the same as before but you will be asking cron to run it every Sunday (0) at 1pm (00 13). Make sure to choose a different day/time so that we don’t all run the same command at the same time. More info about cron jobs can be found here. To create the cronjob, do:

crontab cronfile

and everything is now backed up! To check that it has been registered, you can run:

crontab -l

Group vision and ethics


Cultivating a safe group culture

Enjoyable, high-quality research can only be conducted when you feel safe, secure, and supported. All group member are thus dedicated to a harassment-free experience for everyone, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age, and/or religion. We do not tolerate harassment by and/or of members of our group in any form.

In addition to making group members feel safe and secure, diversity and inclusivity has numerous benefits to us all. Put simply, the greater the mix of people in our group, the greater the mix of skills, experiences, perspectives, and ideas we can collectively draw on. But the benefits of diversity and equality cannot be fully achieved without creating an inclusive environment.

To report an issue, please contact Mathieu; all communication will be treated as confidential. Please be advised that as a university employee, Mathieu is a mandated reporter, and must forward your complaints to the Title IX office if they indicate that sexual harassment or assault has taken place. If you do not feel comfortable contacting Mathieu directly, please feel free to contact a member of the Dartmouth Title IX office.

Mental Health

There is increasing evidence that certain attributes of PhD research may challenge your mental health. Specific factors driving this include:

  • Low pay and quality-of-life issues, particularly as a function of living in the upper valley
  • Feelings of isolation in your research
  • Uncertainty in your research, although it should be noted that, in research of all kinds, it is not just the outcomes that are uncertain, but the questions themselves! 
  • Uncertainty in your post-PhD career
  • So-called “negative results”; i.e. at some point in your research it is likely that certain questions will be more challenging to answer than anticipated, or that you will feel you have spent days/months/years toiling with little to show
  • Burnout; i.e. feeling the need to work endless hours to make up for the above issues, and the subsequent exhaustion

All PhD students come across most of these issues at some level. I strongly encourage everyone in the group to take an active and pre-emptive approach towards the maintenance of their mental health. I assure you that you have the time and resources needed for a highly successful PhD. If there is anything that is placing undue stress, or preventing you from performing at your potential, please do not hesitate to let me know. Every effort will be made to help you access the right support networks.

Group Identity vs Individual Contribution

The purpose of having the “named” Ice Future Group is two-fold: (1) to support each other, (2) to promote our group to newcomers and potential newcomers. While collaborations among group members and with other research groups is highly encouraged, the purpose of the group is not to “brand” the ideas as group ideas, or Mathieu’s ideas. Your project is yours to make your own. You should not feel as though you are presenting Mathieu’s ideas or the group’s projects. For your career and for the development of the science, it is important for you to feel ownership of the project that you are working on. It is good to talk about “we” when it is us working together on developing the project, but you should take credit for ideas that you come up with in the course of your research (That being said, you should always acknowledge project funders when presenting or writing a paper).

Outputs and open science

Authorship on any manuscript or presentation will be openly discussed in group meetings and should, if possible, include everyone who has made a significantcontribution to the work. A “significant contribution” can include but is not limited to, code development, interpretations of primary data, and development of ideas presented in the work. The order of authors on a manuscript or presentation should be dictated by the relative contribution made by each author; in the case these contributions are equal, authors should be listed alphabetically by family name. Where conflict arises, Mathieu will facilitate discussion to help resolve this. I encourage an open dialogue about this matter, ideally via authorship ‘check-ins’ that will likely occur several times over the lifetime of the study. To help inform Editors, reviewers, and readers of our papers, we will include an author contribution statement as part of a paper when necessary.

Your active research product (code, documents, etc.) should be backup up regularly using an off-site, ‘cloud’-based storage system. All Dartmouth staff have access to a nearly-unlimited dropbox and Google Drive allocation (seer rclone above).

All code written as a part of publicly-funded research and used to produce results or make plots in a published paper should be made publicly available using GitHub, ISSM’s repository, or other public code repository. If you feel that there is a good reason for keeping your code exclusive, this should be discussed with Mathieu.

Working hours

I recognise that many of you have personal responsibilities and obligations in addition to your PhD studies. I appreciate that, at times, it can be difficult to balance those demands, and that a classic ‘9-to-5’ day may not be optimal. Because of this, the exact hours you choose to work is up to you. In particular, due to non-work responsibilities and health risks that may be associated with in-person activities, there is no expectation of working on campus or participating in activities if a member feels that these are potential a risk to their personal health. Being “online” (whether virtually or on campus) from 11 AM and 4 PM most days may, however, help facilitate collaborative working and, we hope, lead to a more fulfilling research experience. Where possible, group meetings and events will not be arranged outside these hours to allow participation by all ICG members.

Holidays

You are expected to take (at least) two weeks of time off per year, beyond normal institute holidays (e.g. federal holidays, fall/spring/winter breaks). I strongly encourage you take this time so you can relax, visit family and friends, and generally unwind from the rigours of PhD study. Although not a formal requirement, it is helpful to inform Mathieu in advance when you plan to take holidays or if you will not be present at our group meetings. 

Work on weekends is sometimes OK and/or necessary (especially before deadlines), but will likely lead to a drag on your overall productivity if it is a regular occurence. If you feel that you are having difficulty maintaining a healthy work-life balance, please talk to Mathieu.

Meetings

Group meetings: all “ice future” group members are expected to attend our weekly group meeting if they are not otherwise engaged in other research-related activities (e.g. at conference, attending training or a lecture, etc). Group meetings provide a forum for:

  • Research updates
  • New and interesting papers
  • Old and important papers
  • Papers from other fields
  • Practice conference talks
  • Manuscript in prep figures/outlines
  • Fellowship applications/proposals
  • Essays/articles on being a good scientist, inclusion, creativity, science writing, etc.

The group meeting should be a forum for open discussion, not a venue for one-on-one discussions about very technical research details (that is what one-on-one meetings are for). Mathieu will recommend tabling a discussion if it is derailing the group.

All “ice future” group members are expected to attend our bi-weekly reading group (organized with Helene Seroussi and Colin Meyer’s group) and the ice+climate seminars. Let me know if you are also interested in participating in the weekly ISSM teleconference.

Individual meetings: These will occur either weekly or on an ad-hoc basis as personal situations require. These will give you an opportunity to discuss your progress and any administrative issues that you need addressed. You are encouraged to come fully prepared for individual meetings with questions or issues that you would like help with, or ideas for further work; in this way, discussions can be focused such that all concerns are addressed. Ideally, in a one-on-one meeting, we should discuss: (i) what were your plans from last meeting; (ii) work undertaken; (iii) issues arising; and (iv) a forward plan until the next meeting. Such reports are an important way to self-monitor your progress, as well as keeping your supervisor(s) informed of both positive and negative developments. 

If you are having trouble meeting deadlines that we have previously agreed upon, please do not work yourself an unhealthy amount to attempt to meet those deadlines. Please talk to Mathieu about why you are having trouble meeting the deadline, and we will discuss how you can potentially work more efficiently or set more reasonable deadlines.

The purpose of these meetings is not for you to only report on what went right. Often the most pressing issue is a roadblock in the research or a failure. This is not a bad thing! I am here to help you get through those roadblocks or find an alternate route to achieve your ultimate goal. Ideally, feedback should be a roughly proportional mix of recognizing successes and analyzing failures.

Please inform Mathieu of holidays or notable absences in advance. Permission for holiday is very rarely required, but please respect key deadlines within the calendar year and the fact we work in a research group. It is important to take holiday, respect weekends (or time in lieu) and establish a sustainable work-life balance. It is also important to respect the time and efforts of others, and the contribution of funders, and to note that effective working will improve the quality of your research. Where there are key time pressures, it is important to prioritize work.

Individual Development Plans

An individual development plan (IDP) is a worksheet that identifies your current strengths, and those which you would like to develop over the next few years. Group members will fill one out early in working with Mathieu and revise it on a yearly basis. The document is simply a way to pause, be thoughtful about your goals, and communicate those goals to Mathieu in a way that he can follow up on.

Communication

Please give consideration to the timing of the email with respect to what the recipient needs to do; for example, try not to send an email at after 5pm for something that is required for a 10am meeting the next day. Different people work or respond to emails at different times of the day or weekend, and as stated earlier in this documents, those hours will not be prescribed. That being said, no group members are required nor should feel obliged to reply to email/slack messages outside of their typical work hours. However, prompt replies to emails, within work hours, is helpful. 

Journals

You should be familiar with recently published material relevant to your PhD project. Below are some academic journals that may be of interest:

Signing-up to ‘mail alerts’ from specific journals and more general publication ‘feeds’ (e.g. Google Scholar or Web of Science) are highly recommended; by doing this, you can be kept informed of newly published literature related to your studies.

Conferences

Conferences and workshops are, by far, the best way to meet other researchers (important for developing collaborations in the long run), disseminate your research in a timely fashion and learn about what others are doing. For US-based researchers in glaciology, there are a few conferences, some regular and others less so that are valuable venues for making connections and presenting your work.

  • AGU Fall Meeting – annual (mid-December)- THE huge meeting for Earth scientists in the US, 20k+attendees, but always lots of good cryosphere content
  • EGU General Assembly – annual (April/May) typically in Vienna – smaller European version of AGU (still 10k+ though), good way to meet European cryo community, which is larger than American community 
  • West Antarctic Ice Sheet Workshop – annual (Sep/Oct) – small workshop (<100 attendees), mostly US participants, great way for researchers starting out to meet big names in field and program managers from funding agencies
  • International Glaciological Society Symposia – typically 2-3 per year – topics vary greatly, but always focused on ice topics, usually one symposium per year is more general (i.e. ice and climate change), usually anywhere from 50-400 attendees depending on topic
  • AGU Ocean Sciences – even years (early spring) – AGU meeting focused on ocean topics, typically some ice/ocean sessions, still big – 5k+ attendees
  • SIAM/APS Meetings – applied math and physics meetings, typically large, but a good venue to talk about more technical/mathematical aspects of your work to people outside of glaciology

Thanks, and please enjoy your time in the “ice future” group!

These Guidelines borrow heavily and are modified from the ice and Climate group vision from Alex Robel, and the Basin Research Group Code of Conduct, assembled by Chris Jackson (basinsresearchgroup.com).


Contact

207 Fairchild Hall
Department of Earth Sciences
Dartmouth College
Hanover, NH 03755