Skip to content

Getting Started at SCOREC

Jump to bottom
Jacob Merson edited this page Aug 30, 2023 · 16 revisions

This page introduces new users to getting an environment set up on SCOREC workstations. It covers the most basic Linux configurations needed to compile the SCOREC software stack and begin development.

Table of Contents

Logging in

After getting an account on SCOREC systems you should have a username and password. To access scorec systems, you must first go through the gateway machine at SCOREC called jumpgate. Running this from a terminal on your home computer will access jumpgate. 

  ssh [email protected]

Enter your password at the prompt and you should end up logged into jumpgate.

If you are off campus (not on the RPI network) use the jumpgate multi-factor authentication gateway machine: 

  ssh [email protected]

From here you can log in to any other SCOREC workstation. A list of workstations and their specs can be found here: https://wiki.scorec.rpi.edu/wiki/index.php/List_of_Computers .

Since you're already inside SCOREC systems, you don't need to repeat your username or scorec.rpi.edu. 

  ssh mastermind

File Systems

There are several directories at SCOREC where you can put your files. The two most important ones are your home directory and your fasttmp directory. Your home directory is a safe place for important but not too large files. After logging in to a SCOREC machine your are in your home directory. 

  /users/myusername/

The /lore directory is a much bigger space suitable for keeping a copy of the SCOREC code for compiling and testing, as well as input and output data for your programs. However, any important code changes should be committed to the source code repository and important files should be moved to your home directory if possible. Here is the command to move to your /lore directory. 

  cd /lore/myusername/

These directories are conveniently available on all SCOREC machines, so they look the same no matter where you log in and changes made on one machine show up in another.

Moving Files

To move files to and from the SCOREC systems, a program similar to ssh called scp is useful. For example, to copy a file called mydata.txt from your home computer to your SCOREC home directory, run this on your home computer. 

  scp mydata.txt [email protected]:mydata.txt

Similarly, to copy the same file from your SCOREC home directory onto your home computer, run this on your home computer. 

  scp [email protected]:mydata.txt mydata.txt

As you can see, scp is a lot like cp except the source and destination files can be on different machines.

Replace `jumpgate` with `jumpgate-mfa` in the above commands if you are off campus.

Modules

There are several pieces of third-party software required to compile SCOREC code, as well as other programs that you may find useful in development. For various reasons these are not available by default, and need to be activated through the module system.

First setup the module environment for RedHat. Instructions here: https://wiki.scorec.rpi.edu/wiki/index.php/Red_Hat_Environment

For building PUMI, We have prepared a basic set of modules necessary to compile the code. This script should be executed once right after logging in to a workstation. 

  source env-scorec.sh

The file is available here: https://raw.githubusercontent.com/SCOREC/core/master/env-scorec.sh

It will also be in the SCOREC code repository at core/env-scorec.sh if you download that with Git, see the next step:

Git and Github

Git is SCOREC's source code repository management program. It is used to synchronize changes made by programmers to and from a central source code repository, as well as individual distributed copies of it. A great interactive tutorial is here https://pcottle.github.io/learnGitBranching/ .

Github is SCOREC's project hosting provider. It provides web pages, wikis, permission control, and activity logs for each SCOREC project, and contains each project's source code repository. Here is the command that will checkout a copy of all the code from git.

SSH protocol

The SSH protocol can be used for communicating with GitHub on the command line (e.g., commands like 'git clone [email protected]:<repo></repo>'). The alternative is to use HTTPS. SSH supports running pull/push/etc. commands without typing my password each time and avoids authentication tokens needed by password-less HTTPS access. If you want to setup SSH based communications running the following commands on SCOREC. Note, they assume that you do not have an existing default SSH keypair (run 'ls ~/.ssh' and look for 'id_rsa[.pub]'). 

ssh-keygen #accept all the defaults by hitting enter at each prompt
cat ~/.ssh/id_rsa.pub

In your browser login to GitHub, click your profile icon in the top right, then 'Settings'. In the page that appears select the 'SSH and GPG keys' menu item on the left. In the top right corner of the middle frame there will be a big green 'New SSH Key'. Paste your key (everything output from 'cat') into the 'key' field, set the title to 'SCOREC' and leave 'key type' as 'Authentication key'.

Once this is done you should be able to clone/push/pull via SSH ('[email protected]:....') without entering your password.

Cloning PUMI

To clone PUMI, run this in your /lore directory on a SCOREC workstation. 

  git clone https://github.com/SCOREC/core.git core

Compiling the Stack

After running the above subversion command, you have a new directory called core containing the code. Move into it. 

  cd core

If this copy is left alone for a while, chances are new changes are made by other programmers that you are not aware of. To update and get all the latest changes, run this. 

  git pull

Now to compile the code for the first time. In the core directory, make a build directory to contain the compiled files and move into it 

mkdir build
cd build

Next you will need to configure some options related to how the code is compiled. There is already an example script setting default options: 

  source ../config.sh

If all goes well CMake will configure the code and print output that ends like this: 

&#45;&#45; Configuring done
&#45;&#45; Generating done
&#45;&#45; Build files have been written to&#58; /lore/myusername/core/build

Now compiling all the code is as simple as running the following command. 

  make -j 4

The -j 4 option tells the compilation system to compile 4 files at a time, which makes things faster on machines that have multiple cores. Most SCOREC workstations do.

Again, if all goes well you will not see any compilation errors.

Additional Documentation

Addition documentation is in each source directory in .tex files. These serve as a tie in between the mathematics and algorithms and the implementation. To generate PDFs from these files, run the script latex.sh from the build directory. 

  source ../latex.sh

There should now be a doc folder in the build directory containing all of these documents.

Clone this wiki locally