CAMPARI Documentation - Introduction

Download and Install

Instructions on how to obtain a copy of CAMPARI are provided on the Download page. Installation instructions are found in the corresponding section of the documentation. Please note that we have almost exclusively used CAMPARI on commodity hardware using Intel and occasionally AMD chips running more or less standard Linux operating systems of the RedHat (CentOS), SuSE, or Ubuntu flavors. The current (2017) Piz Daint supercomputer at the Swiss Supercomputing Center (CSCS), which is a Cray system, also successfully runs the CAMPARI software (CPU only). If you manage to build the program on unusual hardware or other operating systems, please let us and the rest of the user base know via our SourceForge page. We ourselves have compiled but not used extensively version on both Windows and MacOS.

Start Running Simulations

Unlike most other simulation software, CAMPARI uses only a single executable (possibly in different flavors, compiling in MPI or OpenMP support or both) that is driven exclusively by a key-file. The only exception to this is the data mining work flow that obviates the notion of a simulation system (executable "camp_ncminer"). In our opinion, having all or most of the offered functionality "under the same hood" simplifies working with CAMPARI. The basic command line for running any CAMPARI simulation or analysis task in a shared memory parallel execution mode will therefore be (assuming a Unix-shell):

cd ${EXEC_DIR}/
${CAMPARI_HOME}/bin/{ARCH}/campari_threads -k ${EXEC_DIR}/sample.key > sample.log

CAMPARI always writes to the current working directory, and will overwrite output files with nonunique names. Again, this is intended, and differs from the work flow implemented by other simulation software. In serial or OpenMP-only execution, the log-file will be written to standard out and should normally be captured for inspection ("sample.log" above). The above command line also makes it clear that a thorough understanding of the relevant keywords is what makes CAMPARI an efficient tool in the users' hands.
A comprehensive list of all keywords is part of the documentation, and typically this is the file users will refer to most often. In the beginning, however, it may prove useful to have a look at our tutorials. The latter have the advantage of leading the reader through a series of steps that construct a key-file suitable for the computation the respective tutorial is concerned with. This allows an easier point of entry as it filters the information down for the scope of a specific simulation. Keywords, input and output files, and some special topics (e.g., sections of parameter files) are html-linked throughout the documentation allowing easy navigation through sets of related content (also from the tutorials).
All CAMPARI simulations require at least two auxiliary input files, a file with a sequence specifying the system to be simulated, and a parameter file. There is a section of the documentation dedicated to explaining the formats of user-generated input files (such as the sequence file). The parameter files are editable, but are shipped with CAMPARI under the assumption that they are most commonly going to be used "as is". A list is provided here, and their structure is explained in another dedicated section of the documentation.

Look at the Output

When running simulations with it, CAMPARI can print spatial information (trajectory data) of the system evolving under some form of sampling algorithm in a number of community formats. CAMPARI will also produce a variable number of additional output files documented in detail elsewhere. Almost all of the analyses can be performed "on-the-fly" meaning that data are accumulated and averaged throughout the simulation. This is unusual, but can be an advantage as it circumvents writing large amounts of data to disk. For quantities which rely on precise details of fluctuations (such as most free energy estimates), this can be a favorable trade-off. It is of course possible to use the key-file to disable all auxiliary analysis and analyze the trajectory data during post-processing. This would mimic the more traditional work flow in the simulation community. In exactly the same vein, CAMPARI can analyze a preexisting trajectory in a special analysis mode. This means it can be, with minimal modifications, used to perform mundane tasks such as the conversion of trajectories between different formats.

Optimal Use of CAMPARI

The most important key to efficient use of any molecular simulation software is a sound understanding of statistical mechanics. It is of course outside of the scope of the software and this documentation to address this. CAMPARI does, however, attempt to simplify things as follows:
  • CAMPARI attempts to simplify certain auxiliary tasks such as the generation of random starting structures for running otherwise identical simulations in "batch"-mode.
  • We have attempted to write the documentation in such a way that it explicitly mentions technical issues ("closet skeletons") pertaining to implemented simulation algorithms. This will not always be comprehensible to nonexperts, but should allow more experienced users to make appropriate choices more easily. While reading of the corresponding literature is indispensable, even that will rarely cover all implementation details.
  • CAMPARI allows a great deal of customization in crucial parts of the algorithms, such as for interaction functions (force field). It can therefore be used as an efficient exploration tool for canonical elements and assumptions of and in force field design.
As a full-fledged trajectory analysis suite, CAMPARI contains the functionality of many packages dedicated to this task. In addition, it contains unique algorithms or unique parallel implementations thereof, in particular in the field of unsupervised data mining (see here for a starter). The obvious benefit for the user is that you only need to learn the basic mechanics of a simple program to perform these rather different tasks.
Most speed-limiting algorithms within CAMPARI have gone through some form of performance optimization and their workload can be distributed to all the cores of a shared memory architecture by means of OpenMP. Nonetheless, CAMPARI cannot compete with the speed of a program such as GROMACS, in particular for the types of applications GROMACS has been optimized for, i.e., explicit solvent, Cartesian space molecular dynamics calculations with 3- or 4-point water models where the majority of the system is solvent. In comparison, CAMPARI, for example, maintains double-precision arithmetics throughout all computations. It is also written in a form that allows modifications and extensions to be accomplished relatively quickly for programmers with any form of Fortran savvy. CAMPARI also maintains an internal representation of the systems it allows simulations of. This is normally an advantage for the user (assuming the systems of interest are supported of course) and in many analysis-related tasks, but affects both performance and code size adversely. Of course, with a small developer core, CAMPARI cannot realistically be compared to software packages grown over the course of decades such as AMBER, CHARMM, or the aforementioned GROMACS. It is, however, being actively maintained and developed, is well-tested, and offers some unique features.

Modifying CAMPARI

We provide a preliminary section on development. This is meant as a first place of reference for those who wish to edit CAMPARI to add or modify features. We hope that in the future all users resort to the SourceForge pages more such that these pages can eventually serve as the knowledge repository for working with the code we anticipated originally.

Citing CAMPARI in Your Work

One of the motivations for creating CAMPARI was to use Monte Carlo sampling on biomolecules with a novel implicit solvation model. This combination is one of the unique features within CAMPARI. The implicit solvent model - termed ABSINTH - is introduced in the following publication.
We humbly ask that for now you acknowledge the use of CAMPARI itself by citing the following reference:
Other (to our knowledge) unique features were introduced in the following publications:
  • Andreas Vitalis and Amedeo Caflisch. Efficient Construction of Mesostate Networks from Molecular Dynamics Trajectories. J. Chem. Theor. Comput. 8 (3), 1108-1120 (2012) (tree-based clustering)
  • Nicolas Blöchliger, Andreas Vitalis, and Amedeo Caflisch. A scalable algorithm to order and annotate continuous observations reveals the metastable states visited by dynamical systems. Comput. Phys. Comm. 184 (11), 2446-2453 (2013) (progress index method)
  • Andreas Vitalis and Amedeo Caflisch. Equilibrium sampling approach to the interpretation of electron density maps. Structure, 22 (1), 156-167 (2014) (spatial density restraints)
  • Andreas Vitalis and Rohit V. Pappu. A simple molecular mechanics integrator in mixed rigid body and dihedral angle space. J. Chem. Phys., 141 (3), 034105 (2014) (molecular dynamics integrators in rigid-body/torsional space)
  • Nicolas Blöchliger, Amedeo Caflisch, and Andreas Vitalis. Weighted distance functions improve analysis of high-dimensional data: Application to molecular dynamics simulations. J. Chem. Theor. Comput. 11 (11), 5481-5492 (2015) (dynamic and static weights for data mining)
  • Marco Bacci, Andreas Vitalis, and Amedeo Caflisch. A molecular simulation protocol to avoid sampling redundancy and discover new states. Biochim. Biophys. Acta, 1850 (5), 889-902 (2015) (progress index-guided sampling (PIGS))
As is true for all features implemented in CAMPARI, citations to the original publications will be appreciated greatly by the respective authors. You can find them in CAMPARI's bibliography (please notify us of any inadvertent omissions).
Design downloaded from free website templates.