Difference between revisions of "Setup Tutorial"

From Einstein Toolkit Documentation
Jump to: navigation, search
(→‎Configuring SimFactory for your machine)
 
(29 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
<div style="border: 2px solid black; padding: 4px">
 +
[[File:warning.png|24px]]
 +
<span style="color:red">'''This tutorial is obsolete.'''</span>
 +
Please use: the [http://einsteintoolkit.org/documentation/new-user-tutorial jupyter based one instead]
 +
</div>
 +
 
=Introduction=
 
=Introduction=
 +
<onlyinclude>
 +
Here you will find a step by step guide to downloading, configuring, and running the Einstein Toolkit.  You may use this tutorial on a workstation or laptop, or on a supported cluster.  Configuring the Einstein Toolkit on an unsupported cluster is beyond the scope of this tutorial.  If you find something that does not work, please feel free to edit the wiki or mail [mailto://users@einsteintoolkit.org users@einsteintoolkit.org].
  
−
Here you will find a step by step guide to downloading, configuring, and running the Einstein Toolkit.  You may use this tutorial on a workstation or laptop, or on a supported cluster.  Configuring the Einstein Toolkit on an unsupported cluster is beyond the scope of this tutorial. If you find something that does not work, please feel free to edit the wiki or mail [mailto://users@einsteintoolkit.org users@einsteintoolkit.org].
+
<!-- RH: There already is information about the release in the download URL as well as what OS it was tested on below. No need to duplicate the information
  
 
These instructions were last tested on XX-XXX-XXXX with the ET_XXXX_XX release of the Einstein Toolkit.
 
These instructions were last tested on XX-XXX-XXXX with the ET_XXXX_XX release of the Einstein Toolkit.
 +
-->
 +
 +
==Prerequisites==
 +
 +
When using the Einstein Toolkit on a laptop or workstation you will need a number of packages installed in order to download, compile and use the Einstein Toolkit components. On a Debian, Ubuntu, Linux-Mint, Fedora, Mac OS, Windows 10 based system, install them as follows:
 +
 +
# Debian (stretch, buster)
 +
su -c 'apt-get install build-essential libopenmpi-dev openmpi-bin gfortran git subversion curl gnuplot gnuplot-x11'
 +
# Ubuntu (16.04.2, 17.04)
 +
sudo apt-get install build-essential mpich2? python libmpich2?-dev gfortran git subversion curl gnuplot gnuplot-x11
 +
# Fedora (FC 25, 26)
 +
sudo yum -y install mpich2 python mpich2-devel gsl gsl-devel libjpeg-devel hdf5 hdf5-mpich-devel gcc gcc-c++ gcc-gfortran patch numactl-devel numactl hwloc subversion git openssl-devel lapack-static
 +
 +
# MacOS+MacPorts (Yosemite)
 +
# Install [https://www.macports.org/install.php MacPorts] first, then do
 +
sudo port install subversion git gnuplot szip jpeg gcc46 fftw fftw-3 gsl openssl hdf5 +fortran +gcc46 -universal zlib openmpi +gcc46
 +
# MacOS+Homebrew (Sierra)
 +
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
 +
brew tap homebrew/science
 +
brew install subversion gnuplot subversion gcc fftw gsl hdf5 --with-fortran hwloc jpeg openssl pkg-config szip open-mpi
 +
 +
# Windows10+LinuxSubsystem (Anniversary Update)
 +
# Make sure to install the [https://msdn.microsoft.com/en-us/commandline/wsl/install_guide Linux Subsystem] and you are effectively
 +
# running a Ubuntu Linux systems but have to install a separate X11 server as
 +
# well as making sure that the system can resolve its own hostname
 +
# (last tested with Windows 10 Anniversary Update)
 +
sudo apt-get install build-essential mpich2? python libmpich2?-dev gfortran git subversion curl gnuplot gnuplot-x11
 +
echo "127.0.0.1 $(hostname)" | sudo tee --append /etc/hosts
 +
echo "export DISPLAY=:0.0" >>$HOME/.bashrc
 +
export DISPLAY=:0.0
 +
curl -o /mnt/c/Users/$USER/Downloads/vcxsrv-64.1.19.2.0.installer.exe -L https://downloads.sourceforge.net/project/vcxsrv/vcxsrv/1.19.2.0/vcxsrv-64.1.19.2.0.installer.exe
 +
chmod a+x /mnt/c/Users/$USER/Downloads/vcxsrv-64.1.19.2.0.installer.exe
 +
# the next two lines work in Windows Creators Update (version 1703), on older
 +
# versions you will have to install manually using the file in your
 +
# "Downloads" folder then start VcXsrv from the start menu
 +
/mnt/c/Users/$USER/Downloads/vcxsrv-64.1.19.2.0.installer.exe
 +
/mnt/c/Program\ Files/VcXsrv/vcxsrv.exe &
 +
 +
Installing in addition packages for (Debian package names so your mileage may vary)
 +
 +
pkg-config libfftw3-dev libgsl0-dev libatlas-base-dev libjpeg-dev libssl-dev libhdf5-serial-dev libhwloc-dev hwloc-nox
 +
 +
can speed up the compilation, since Cactus will try and use the system provided versions rather than compile its own. Once you have downloaded the Einstein Toolkit, you can inspect the option list files in simfactory/mdb/optionlists/ which often contain a list of recommended packages at the top of the files.
 +
 +
Please make sure all required packages are correctly installed before proceeding with the next step.
  
 
=Download=
 
=Download=
Line 24: Line 77:
 
==Configuring SimFactory for your machine==
 
==Configuring SimFactory for your machine==
  
−
The ET depends on various libraries, and needs to interact with machine-specific queueing systems and MPI implementations.  As such, it needs to be configured for a given machine.  For this, it uses SimFactory.  Generally, configuring SimFactory means providing an optionlist, for specifying library locations and build options, a submit script for using the batch queueing system, and a runscript, for specifying how Cactus should be run, e.g. which mpirun command to use.  For a cluster, a "machine definition file" is also required.
+
The ET depends on various libraries, and needs to interact with machine-specific queueing systems and MPI implementations.  As such, it needs to be configured for a given machine.  For this, it uses SimFactory.  Generally, configuring SimFactory means providing an optionlist, for specifying library locations and build options, a submit script for using the batch queueing system, and a runscript, for specifying how Cactus should be run, e.g. which mpirun command to use.  <!--For a cluster, a "machine definition file" is also required.-->
  
 
===Laptop/workstation operating systems===
 
===Laptop/workstation operating systems===
  
−
SimFactory contains general support for specific operating systems commonly used on workstations or laptops.  The following table lists the supported operating systems, and the information needed to configure SimFactory on each one.
+
SimFactory contains general support for specific operating systems commonly used on workstations or laptops. Currently this list includes Linux/Ubuntu, Linux/Debian, Linux/Fedora, MacOS/Homebrew, MacOS/MacPorts, Windows10/BashTerminal.  The following table lists the supported operating systems, and the information needed to configure SimFactory on each one.
  
 
{| class="wikitable" style="border: 1pt solid black;"
 
{| class="wikitable" style="border: 1pt solid black;"
Line 61: Line 114:
 
|}
 
|}
  
−
Find your operating system in the list above, and look at the start of the optionlist for instructions on installing any needed libraries for that operating system.
+
Find your operating system in the list above, and look at the start of the optionlist for instructions on installing any needed libraries for that operating system:
  
−
Then, run
+
    head simfactory/mdb/optionlists/<optionlist>
  
−
    simfactory/bin/sim setup-silent --optionlist=<optionlist> --runscript <runscript>
+
This will usually involve installing various libraries using your operating system's package manager.
  
−
where <optionlist> and <runscript> are taken from the table above.  This will create a new "machine definition" for your machine, named after your machine hostname, in simfactory/mdb/machines/<hostname>.ini, as well as write user-specific settings to simfactory/etc/defs.local.ini.
+
Once all required packages have been installed, run
  
−
===Supported clusters===
+
    simfactory/bin/sim setup-silent
  
−
SimFactory comes with support for many of the large supercomputers, and the ET is tested on these at the time of each release. To find out if the cluster you are running on is supported by SimFactory, run
+
After this step is complete you will find your machine's default setup under
 +
./simfactory/mdb/machines/<hostname >.ini
  
−
    sim whoami
+
You can edit some of these settings freely, such as "description", "basedir" etc. Some entry edits could result in simulation start-up warnings and/or errors such as "ppn" (processor-per-node meaning number of cores on your machine), "num-threads" (number of threads per core) so such edits must be done with some care.
−
 
 
−
If this returns
 
−
 
 
−
    Current machine: None
 
−
 
 
−
then unfortunately SimFactory does not support your cluster, and you will need to configure it manually (see Unsupported Machines below).
 
−
 
 
−
If you see
 
−
 
 
−
    Current machine: <name of your cluster>
 
−
 
 
−
then SimFactory supports your cluster.  Run
 
−
 
 
−
    simfactory/bin/sim setup
 
−
 
 
−
from your Cactus directory and answer the questions, and SimFactory will automatically detect the correct option list, submit script and run script.
 
−
 
 
−
===Unsupported machines===
 
−
 
 
−
If there is no existing optionlist or runscript (for a cluster, also a submit script) for your machine, you will need to write them yourself.  It is recommended to start from one of the already-written files for another machine which is as close as possible to the machine you are trying to use.  See [[Configuring a new machine]] for help with this. First, write the option list and run script, and run
 
−
 
 
−
    simfactory/bin/sim setup --optionlist=<optionlist> --runscript <runscript>
 
−
 
 
−
with the new configuration files.  This will create a basic machine definition file in simfactory/mdb/machines named after your hostname.  For a cluster, it is unlikely that this basic file will be enough, as SimFactory needs a lot of information about the details of the cluster.
 
  
 
==Building the Einstein Toolkit==
 
==Building the Einstein Toolkit==
Line 103: Line 133:
 
Assuming that SimFactory has been successfully set up on your machine, you should be able to build the Einstein Toolkit with
 
Assuming that SimFactory has been successfully set up on your machine, you should be able to build the Einstein Toolkit with
  
−
     simfactory/bin/sim build --thornlist path/to/thornlist.th
+
     simfactory/bin/sim build -j2 --thornlist manifest/einsteintoolkit.th
 +
 
 +
Adjust -j2 to match the number of cores your machine possesses if you want to use more or less than 2 parallel build processes. This may take a while, as it compiles all the thorns specified in manifest/einsteintoolkit.th.
 +
</onlyinclude>
  
 
==Running==
 
==Running==
Line 109: Line 142:
 
You can now run the Einstein Toolkit with a simple test parameter file.
 
You can now run the Einstein Toolkit with a simple test parameter file.
  
−
     simfactory/bin/sim submit helloworld --parfile arrangements/CactusExamples/HelloWorld/par/HelloWorld.par
+
     simfactory/bin/sim create-submit helloworld --parfile arrangements/CactusExamples/HelloWorld/par/HelloWorld.par --walltime 0:5:0
  
−
This will submit the simulation to the queue, if you are running on a cluster, or run it immediately in the background if not.  You can check the status of the simulation with
+
This will submit the simulation to the queue naming it "helloworld" and ask for a 5 minutes long job time, if you are running on a cluster, or run it immediately in the background if you are on a personal laptop or workstation.  You can check the status of the simulation with
  
 
     simfactory/bin/sim list-simulations helloworld
 
     simfactory/bin/sim list-simulations helloworld
Line 119: Line 152:
 
     helloworld              [ACTIVE (FINISHED), restart 0000, job id 17456]
 
     helloworld              [ACTIVE (FINISHED), restart 0000, job id 17456]
  
−
once the simulation has finished.  You can look at the output with
+
once the simulation has finished and
 +
 
 +
    helloworld              [ACTIVE (QUEUED), restart 0000, job id 17456]
 +
 
 +
while it still waits to execute and
 +
 
 +
    helloworld              [ACTIVE (RUNNING), restart 0000, job id 17456]
 +
 
 +
while it is running.  Once it finished you can look at the output with
  
 
     simfactory/bin/sim show-output helloworld
 
     simfactory/bin/sim show-output helloworld
  
−
in which you should see the lines
+
in should see the lines (you may have to scroll up bit to see them):
  
 
     INFO (HelloWorld): Hello World!
 
     INFO (HelloWorld): Hello World!
  
 
If you see these line, then congratulations, you have successfully downloaded, compiled and run the Einstein Toolkit!  You may now want to try some of the other tutorials to explore some interesting physics examples.
 
If you see these line, then congratulations, you have successfully downloaded, compiled and run the Einstein Toolkit!  You may now want to try some of the other tutorials to explore some interesting physics examples.

Latest revision as of 13:12, 16 April 2024

warning.png This tutorial is obsolete. Please use: the jupyter based one instead

Introduction

Here you will find a step by step guide to downloading, configuring, and running the Einstein Toolkit. You may use this tutorial on a workstation or laptop, or on a supported cluster. Configuring the Einstein Toolkit on an unsupported cluster is beyond the scope of this tutorial. If you find something that does not work, please feel free to edit the wiki or mail users@einsteintoolkit.org.


Prerequisites

When using the Einstein Toolkit on a laptop or workstation you will need a number of packages installed in order to download, compile and use the Einstein Toolkit components. On a Debian, Ubuntu, Linux-Mint, Fedora, Mac OS, Windows 10 based system, install them as follows: 

# Debian (stretch, buster)
su -c 'apt-get install build-essential libopenmpi-dev openmpi-bin gfortran git subversion curl gnuplot gnuplot-x11'
# Ubuntu (16.04.2, 17.04)
sudo apt-get install build-essential mpich2? python libmpich2?-dev gfortran git subversion curl gnuplot gnuplot-x11
# Fedora (FC 25, 26)
sudo yum -y install mpich2 python mpich2-devel gsl gsl-devel libjpeg-devel hdf5 hdf5-mpich-devel gcc gcc-c++ gcc-gfortran patch numactl-devel numactl hwloc subversion git openssl-devel lapack-static

# MacOS+MacPorts (Yosemite)
# Install MacPorts first, then do
sudo port install subversion git gnuplot szip jpeg gcc46 fftw fftw-3 gsl openssl hdf5 +fortran +gcc46 -universal zlib openmpi +gcc46
# MacOS+Homebrew (Sierra) 
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew tap homebrew/science
brew install subversion gnuplot subversion gcc fftw gsl hdf5 --with-fortran hwloc jpeg openssl pkg-config szip open-mpi

# Windows10+LinuxSubsystem (Anniversary Update)
# Make sure to install the Linux Subsystem and you are effectively
# running a Ubuntu Linux systems but have to install a separate X11 server as 
# well as making sure that the system can resolve its own hostname
# (last tested with Windows 10 Anniversary Update)
sudo apt-get install build-essential mpich2? python libmpich2?-dev gfortran git subversion curl gnuplot gnuplot-x11
echo "127.0.0.1 $(hostname)" | sudo tee --append /etc/hosts
echo "export DISPLAY=:0.0" >>$HOME/.bashrc
export DISPLAY=:0.0
curl -o /mnt/c/Users/$USER/Downloads/vcxsrv-64.1.19.2.0.installer.exe -L https://downloads.sourceforge.net/project/vcxsrv/vcxsrv/1.19.2.0/vcxsrv-64.1.19.2.0.installer.exe
chmod a+x /mnt/c/Users/$USER/Downloads/vcxsrv-64.1.19.2.0.installer.exe
# the next two lines work in Windows Creators Update (version 1703), on older
# versions you will have to install manually using the file in your
# "Downloads" folder then start VcXsrv from the start menu
/mnt/c/Users/$USER/Downloads/vcxsrv-64.1.19.2.0.installer.exe
/mnt/c/Program\ Files/VcXsrv/vcxsrv.exe &

Installing in addition packages for (Debian package names so your mileage may vary) 

pkg-config libfftw3-dev libgsl0-dev libatlas-base-dev libjpeg-dev libssl-dev libhdf5-serial-dev libhwloc-dev hwloc-nox

can speed up the compilation, since Cactus will try and use the system provided versions rather than compile its own. Once you have downloaded the Einstein Toolkit, you can inspect the option list files in simfactory/mdb/optionlists/ which often contain a list of recommended packages at the top of the files.

Please make sure all required packages are correctly installed before proceeding with the next step.

Download

A script called GetComponents is used to fetch the components of the Einstein Toolkit. GetComponents serves as convenient wrapper around lower level tools like git and svn to download the codes that make up the Einstein toolkit from their individual repositories. You may download and make it executable as follows: 

curl -O -L https://raw.githubusercontent.com/gridaphobe/CRL/ET_2017_06/GetComponents
chmod a+x GetComponents

GetComponents accepts a thorn list as an argument. To check out the needed components: 

./GetComponents --parallel https://bitbucket.org/einsteintoolkit/manifest/raw/ET_2017_06/einsteintoolkit.th

This thornlist checks out the entire Einstein Toolkit, including Cactus, the Simulation Factory, the Einstein Toolkit thorns, and Kranc.

Configure and build

The recommended way to compile the Einstein Toolkit is to use the Simulation Factory ("SimFactory").

Configuring SimFactory for your machine

The ET depends on various libraries, and needs to interact with machine-specific queueing systems and MPI implementations. As such, it needs to be configured for a given machine. For this, it uses SimFactory. Generally, configuring SimFactory means providing an optionlist, for specifying library locations and build options, a submit script for using the batch queueing system, and a runscript, for specifying how Cactus should be run, e.g. which mpirun command to use.

Laptop/workstation operating systems

SimFactory contains general support for specific operating systems commonly used on workstations or laptops. Currently this list includes Linux/Ubuntu, Linux/Debian, Linux/Fedora, MacOS/Homebrew, MacOS/MacPorts, Windows10/BashTerminal. The following table lists the supported operating systems, and the information needed to configure SimFactory on each one.

Configuration files
Operating system Option list Run script Notes
Debian debian.cfg debian.sh
Ubuntu/Linux Mint ubuntu.cfg debian.sh
Fedora fedora.cfg debian.sh Run "module load mpi" before compiling or running, and you may need to log out and back in if you have just installed mpich to make the module command work.
OS X (with MacPorts) osx-macports.cfg osx-macports.run
OS X (with HomeBrew) osx-homebrew.cfg generic-mpi.run

Find your operating system in the list above, and look at the start of the optionlist for instructions on installing any needed libraries for that operating system: 

   head simfactory/mdb/optionlists/<optionlist>

This will usually involve installing various libraries using your operating system's package manager.

Once all required packages have been installed, run 

   simfactory/bin/sim setup-silent

After this step is complete you will find your machine's default setup under ./simfactory/mdb/machines/<hostname >.ini

You can edit some of these settings freely, such as "description", "basedir" etc. Some entry edits could result in simulation start-up warnings and/or errors such as "ppn" (processor-per-node meaning number of cores on your machine), "num-threads" (number of threads per core) so such edits must be done with some care.

Building the Einstein Toolkit

Assuming that SimFactory has been successfully set up on your machine, you should be able to build the Einstein Toolkit with 

   simfactory/bin/sim build -j2 --thornlist manifest/einsteintoolkit.th

Adjust -j2 to match the number of cores your machine possesses if you want to use more or less than 2 parallel build processes. This may take a while, as it compiles all the thorns specified in manifest/einsteintoolkit.th.


Running

You can now run the Einstein Toolkit with a simple test parameter file. 

   simfactory/bin/sim create-submit helloworld --parfile arrangements/CactusExamples/HelloWorld/par/HelloWorld.par --walltime 0:5:0

This will submit the simulation to the queue naming it "helloworld" and ask for a 5 minutes long job time, if you are running on a cluster, or run it immediately in the background if you are on a personal laptop or workstation. You can check the status of the simulation with 

   simfactory/bin/sim list-simulations helloworld

You should see 

   helloworld              [ACTIVE (FINISHED), restart 0000, job id 17456]

once the simulation has finished and 

   helloworld              [ACTIVE (QUEUED), restart 0000, job id 17456]

while it still waits to execute and 

   helloworld              [ACTIVE (RUNNING), restart 0000, job id 17456]

while it is running. Once it finished you can look at the output with 

   simfactory/bin/sim show-output helloworld

in should see the lines (you may have to scroll up bit to see them): 

   INFO (HelloWorld): Hello World!

If you see these line, then congratulations, you have successfully downloaded, compiled and run the Einstein Toolkit! You may now want to try some of the other tutorials to explore some interesting physics examples.

Retrieved from "https://docs.einsteintoolkit.org/et-docs/index.php?title=Setup_Tutorial&oldid=8431"