Using StarCluster with PySPH

StarCluster is an open source cluster-computing toolkit for Amazon’s Elastic Compute Cloud (EC2). StarCluster has been designed to simplify the process of building, configuring, and managing clusters of virtual machines on Amazon’s EC2 cloud.

Using StarCluster along with PySPH’s MPI support, you can run PySPH code on multiple instances in parallel and complete simulations faster.

Installing StarCluster

StarCluster can be installed via pip as

$ pip install starcluster

Configuring StarCluster

Creating Configuration File

After StarCluster has been installed, the next step is to update your StarCluster configuration

$ starcluster help

StarCluster - (
Software Tools for Academics and Researchers (STAR)
Please submit bug reports to - ERROR - config file /home/user/.starcluster/config does not exist
[1] Show the StarCluster config template
[2] Write config template to /home/user/.starcluster/config
[q] Quit
Please enter your selection:

Select the second option by typing 2 and press enter. This will give you a template to use to create a configuration file containing your AWS credentials, cluster settings, etc. The next step is to customize this file using your favorite text-editor

$ emacs ~/.starcluster/config

Updating AWS Credentials

This file is commented with example “cluster templates”. A cluster template defines a set of configuration settings used to start a new cluster. The config template provides a smallcluster template that is ready to go out-of-the-box. However, first, you must fill in your AWS credentials and keypair info

[aws info]
aws_access_key_id = # your aws access key id here
aws_secret_access_key = # your secret aws access key here
aws_user_id = # your 12-digit aws user id here

To find your AWS User ID, see Finding your Account Canonical User ID

You can get your root user credentials from the Security Credentials page on AWS Management Console. However, root credentials allow for full access to all resources on your account and it is recommended that you create separate IAM (Identity and Access Management) user credentials for managing access to your EC2 resources. To create IAM user credentials, see Creating IAM Users (Console) For StarCluster, create an IAM user with the EC2 Full Access permission.

If you don’t already have a keypair, you can generate one using StarCluster by running:

$ starcluster createkey mykey -o ~/.ssh/mykey.rsa

This will create a keypair called mykey on Amazon EC2 and save the private key to ~/.ssh/mykey.rsa. Once you have a key the next step is to fill in your keypair info in the StarCluster config file

[key mykey]
key_location = ~/.ssh/mykey.rsa

Also, update the following information for the smallcluster configuration:

[cluster smallcluster]
KEYNAME = mykey

Now that the basic configuration for StarCluster is complete, you can directly launch instances using StarCluster. However, note that EC2 charges are not pro rata and you will be charged for an entire hour even if you run an instance for a few minutes. Before attempting to deploy an instance/cluster you can modify the following information in your cluster configuration:

[cluster smallcluster]

Now you can launch an EC2 instance using:

$ starcluster start smallcluster

You can SSH into the master node by running:

$ starcluster sshmaster smallcluster

You can transfer files to the nodes using the get and put commands as:

$ starcluster put /path/to/local/file/or/dir /remote/path/
$ starcluster get /path/to/remote/file/or/dir /local/path/

Finally, you can terminate the instance by running:

$ starcluster terminate smallcluster

Setting up PySPH for StarCluster

Most of the public AMIs currently distributed for StarCluster are outdated and have reached their end of life. To ensure a hassle-free experience while further extending the AMI and installing packages, you can use the 64 bit Ubuntu 16.04 AMI with AMI ID ami-01fdc27a which has most StarCluster dependencies and PySPH dependencies installed.

Base AMI for PySPH [Optional]

The file which can be found in the starcluster directory in the PySPH repository automatically launches a vanilla 64-bit Ubuntu 16.04 instance, installs any necessary StarCluster and PySPH dependencies and saves an AMI with this configuration on your AWS account

$ ./

The AMI ID of the generated image is stored in AMI_ID. You can also see a list of the AMIs currently in your AWS account by running

$ starcluster listimages

Cluster configuration for PySPH

Modify your StarCluster configuration file with the following information. Launching a cluster with the following configuration will start 2 t2.micro instances, install the latest version of PySPH in each and keep track of the nodes loaded in /home/pysph/PYSPH_HOSTS:

[cluster pysphcluster]
KEYNAME = mykey
CLUSTER_SIZE = 2 # Number of nodes in cluster
NODE_IMAGE_ID = ami-01fdc27a # Or AMI ID for base AMI generated previously
NODE_INSTANCE_TYPE = t2.micro # EC2 Instance type
PLUGINS = pysph_install

[plugin pysph_install]
setup_class = sc_pysph.PySPHInstaller

Also, copy from the starcluster directory to ~/.starcluster/plugins/

Running PySPH scripts on a cluster

You can start the cluster configured previously by running

$ starcluster start -c pysphcluster cluster

Assuming your PySPH file is in the local home directory, you can first transfer this file to the cluster:

$ starcluster put -u pysph cluster ~/ /home/pysph/

Then run the PySPH code as:

$ starcluster sshmaster -u pysph cluster "mpirun -n 2 --hostfile ~/PYSPH_HOSTS python ~/"

Finally, you can get the output generated by PySPH back by running:

$ starcluster get -u pysph cluster /home/pysph/cube_output .