Installing and Testing FabSim
This document describes how to install FabSim3 and perform basic tests. The full documentation is available at http://fabsim3.readthedocs.io or in docs/index.rst (locally).
To use FabSim3, you will need to have git installed, as FabSim3 requires git to install plugins.
The "pip" way
FabSim requires the following Python modules:
- PyYAML (any version)
- fabric3 (1.1.13.post1 has worked for us)
You can install using
pip3 install PyYAML,
pip3 install numpy and
pip3 install fabric3.
To perform the Py.test tests (not required for using FabSim, but essential for running the tests), you will need
Using apt on Ubuntu (tried with 18.04 Bionic Beaver)
(when using a server version, make sure you add
universe at the end of the first line of
sudo apt install sshd(if you want to run jobs on localhost)
sudo apt install git
sudo apt install python3-yaml
sudo apt install python3-numpy
sudo apt install python3-pip
sudo apt install python3-pytest-pep8(this will also install py.test for Python3)
- go to the
pip3 install Fabric3-1.14.post1-py3-none-any.whl
Note for Mac users
For Mac users, you might also need ssh-copy-id. This can be installed using
brew install ssh-copy-id.
Clone the code from the GitHub repository.
Ensure that the main FabSim3 directory is in your $PYTHONPATH environment variable and that the
fabsimcommand can be launched from the command line. An easy way to accomplish this is by adding the following to the end of your $HOME/.bashrc file:
export PATH=(path of your FabSim3 directory)/bin:$PATH export PYTHONPATH=(path of your FabSim3 directory):$PYTHONPATH
Note that you may have to restart the shell for these changes to apply.
machines_user.yml. Modify its contents so that it matches with your local settings. For first (local) testing, one must change the settings under the sections
localhost:so as to update the paths of FabSim directory and lammps executable respectively.
Note for Mac Users
For Mac Users, be sure to override the default home directory, by switching the
home_path_templatevariable by uncommenting the following line:
To enable use of FabSim on your local host, type
fab localhost setup_fabsim.
- As part of this command, you will be logging in to your own machine through SSH once, which can trigger a password prompt. In this case, simply type the password for the machine in which you are running these commands.
To enable use of FabSim on any other remote machine, make sure that (a) machines.yml contains the specific details of the remote machine, and (b) machines_user.yml contains the specific information for your user account and home directory for the machine. After that, simply type 'fab <machine_name> setup_fabsim'.
- NOTE: FabSim commands can now be launched using the
fabsimcommand. Note that some older tutorials might use
fabcommands instead of
fabsim. The two commands can be used interchangably, although the
fabsimcommand gives clearer outputs and can be launched from anywhere (
fabcan only be used within the FabSim installation directories).
By default, FabSim3 comes with the FabMD plugin installed. Other plugins can be installed, and are listed in deploy/plugins.yml.
To install a specific plugin, simply type:
fabsim localhost install_plugin:<plug_name>
To create your own plugin, please refer to doc/CreatingPlugins.md
If you have already installed FabSim and want to update to the latest version, in your local FabSim directory simply type
git pull. Your personal settings like the
machines_user.yml will be unchanged by this.
To update plugins you will have to
git pull from within each plugin directory as and when required.
The easiest way to test FabSim is to simply go to the base directory of your FabSim installation and try the examples below.
Note: Mac users may get a
ssh: connect to host localhost port 22: Connection refused error. This means you must enable remote login. This is done in
System Preferences > Sharing > Remote Login.
List available commands.
- Simply type
FabDummy testing on the local host
fabsim localhost install_plugin:FabDummy anywhere inside your FabSim3 install directory.
FabDummy plugin will be downloaded under
<fabsim home folder>/plugins/FabDummy
- To run a dummy job, type
fabsim localhost dummy:dummy_test
- To run an ensemble of dummy jobs, type
fabsim localhost dummy_ensemble:dummy_test
- for both cases, i.e., a single dummy job or an ensemble of dummy jobs, you can fetch the results by using
fabsim localhost fetch_results
For more advanced testing features, please refer to the FabDummy tutorial at https://github.com/djgroen/FabDummy/blob/master/README.md.
LAMMPS testing on the local host
- Install LAMMPS (see http://lammps.sandia.gov for detailed download and installation instructions).
machines_user.ymlto make the
lammps_execvariable point to the location of the LAMMPS executable. e.g.,
- FabSim contains sample LAMMPS input files, so there's no need to download that.
- (first time use only) Create the required FabSim directory using the following command:
fabsim localhost setup_fabsim.
- Before run LAMMPS test data set, you should install FabMD which provides functionality to extend FabSim3's workflow and remote submission capabilities to LAMMPS specific tasks. Please install it by typing
fabsim localhost install_plugin:FabMD
- Run the LAMMPS test data set using:
fabsim localhost lammps_dummy:lammps_dummy,cores=1,wall_time=1:00:0.
fabsim localhost fetch_resultsto copy the output of your job in the results directory. By default this will be a subdirectory in
Creating the relevant FabSim directories on a local or remote host
- Ensure that you have modified
machines_user.ymlto contain correct information for your target machine.