Package: scine-puffin
IntroductionSCINE Puffin is a calculation handler for SCINE Chemoton. Thus, it bridges the gap between high level exploration jobs for reaction networks and  basic quantum chemical calculations. Making use of the abstractions defined the SCINE Core and SCINE Utilities  modules it provides the means to define and execute jobs that generate new data for reaction networks. SCINE Puffin is designed as an instanced runner that, once bootstrapped, continuously processes requested jobs. It is built to work in containerized environments (Docker, Apptainer/Singularity).License and Copyright InformationFor license and copyright information, see the fileLICENSE.txtin this
directory.InstallationPrerequisitesBasic RequirementsThus far Puffin is expected to run on Linux systems and possibly on OSX systems,
Windows-based architectures are not specifically supported.
Using containers and the integrated subsystem feature of Windows 10 it should
be possible to toy around with it nonetheless. This is, however, not a case
we would recommend for inexperienced users.Puffin collects a variety of programs to run calculations. In order to get a
minimal working version of Puffin to run on a given system, the following
programs/packages are required:Python3CMake >= v3.12GitGCC >= v7.0.0, CLang >= v6.0.0 (Unix), ICC >= v2017.01Boost >= v1.64.0A MongoDB including the C++ bindingsPuffin Python PackageThe main Python package Puffin requires the several additional packages, which will be
automatically installed when installing Puffin usingpip. These packages are
listed in the filerequirements.txt.For development work, a few extra packages are needed; these are listed in the filerequirements-dev.txt.Puffin InstanceA usable Puffin instance will require at least a minimal set of additional C++
components. These components do not need to be compiled by the user, but instead
they will be compiled when bootstrapping the instance. These components are:SCINE DatabaseSCINE MolassemblerSCINE ReaDuctSCINE UtilitiesInstallationPuffin can be installed using pip (pip3) once the repository has been cloned:gitclone<puffin-repo>pipinstall./puffinA non super user can install the package using a virtual environment, or
the--userflag.It is also possible to run/install a dockerized version of Puffin. For more
details on this please see theUsage->Dockersection of this documentation.The documentation can be found online, or it can be built using:cdpuffinmake-CdocshtmlIt is then available at:<browsername>docs/build/html/index.htmlIn order to build the documentation, you need a few extra Python packages wich
are not installed automatically together with Puffin. In order to install them,
runcdpuffinpipinstall-rrequirements-dev.txtUsageBasic UsageIn order to use Puffin, at least one Puffin instance has to be generated.
Each instance will then separately accept and run jobs later on.
In order to setup a first instance, prepare a folder:mkdirpuffin_instancecdpuffin_instanceand generate the default configuration file for an instance inside it:python3-mscine_puffinconfigurevipuffin.yamlAfterwards it is possible to configure the instance to your liking, by editing
the generatedpuffin.yamlfile.It is also possible to enter configurations via environment variables.
The environment variables override the variables given in the configure file.
Any configuration option can be given via the environment as:exportPUFFIN_<key1>_<key2>_<key3>=<value>or as a concrete example:exportPUFFIN_DATABASE_PORT=27019The settings for each program are explained in the documentation of that
particular program. The general settings pertaining to the daemon and Puffin in
general are explained separately in a section below.After (if desired) editing the settings it is possible to bootstrap Puffin and
thus install all programs that have to be installed in order to run the
instance.python3-mscine_puffin-cpuffin.yamlbootstrapAll programs that will be installed are marked in the configuration asavailableand have asourcepath given.
Bootstrapping the instance will generate a source file calledpuffin.sh. It
contains all environment variables that have to be set in order to make the
instance find all installed programs.
Hence, source the installed programs using:sourcepuffin.shThe Puffin instance is now ready to be used. Start and stop the actual daemon by
usingpython3-mscine_puffin-cpuffin.yamlstartandpython3-mscine_puffin-cpuffin.yamlstopIf thepuffin.yamlis not given, the default options will be used. Once again,
any environment variables precede the loaded file.DockerIt is possible to generate a containerized version of Puffin using Docker or
Podman. TheDockerfileis present in the directorycontainer/dockerof this repository.
The generated Docker image includes all packages required to run Puffin with the
default set of programs. When running the image it is possible to configure the
options of the Puffin instance. We recommend mounting a scratch directory e.g./scratch/puffininto the Docker.Furthermore, it is possible to dry-run (without a database) a version of the
image which will still execute the bootstrap stage of Puffin.
It is then possible to copy the clean/scratch/puffinfolder and then
shorten (skip) the bootstrap step in other instances of the image by
pasting this copied folder into the/scratchfolder mounted into the
other instances. However, for this to properly work we advise caution when
bootstrapping with-march=nativeflags for the programs in the initial
instance.Command Line SetupIn order to build the image, executesudodockerbuild-t<imagename>The image will bootstrap and start running a Puffin instance as soon as
the image is run with:dockerrun-it--mountsrc=<pathtolocalfolder>,target=/scratch,type=bind<imagename>Any configuration can be done by adding environment variables in the run command.Docker Compose SetupA minimal version of docker-compose input starting an instance of Puffin is
deposited in thedockerfolder located in the top directory of this
repository.Basic Settings and ConfigurationThe full list of all options to be set is given in the online documentation in
theSettingssection. Furthermore, this documentation can be read directly
from the doc-string of thescine_puffin.config.Configurationclass.
The settings of each program can be read from the documentation of the
respective class interfacing the program, e.g.scine_puffin.programs.sparrow.Sparrow.How to CiteWhen publishing results obtained with Puffin, please cite the corresponding
release as archived onZenodo(DOI
10.5281/zenodo.6695461; please use the DOI of the respective release).In addition, we kindly request you to cite the following article when using Puffin:
J. P. Unsleber, S. A. Grimmel, M. Reiher,
“Chemoton 2.0: Autonomous Exploration of Chemical Reaction Networks”,
arXiv:2202.13011 [physics.chem-ph].Support and ContactIn case you should encounter problems or bugs, please write a short message
toscine@phys.chem.ethz.ch.