An overview of the src directory

From a conceptual standpoint, the src directory contains all the C++ code specific to Rosetta. The directory structure within Rosetta delineates conceptual dependencies. A Rosetta developer should keep in mind the layered architecture depicted in the figure below. The arrows represent allowed dependency flows. Any code dependency on directories not accessible by following the arrows is not allowed. A strict vertical code dependency has been observed thus far in writing Rosetta code. This figure demonstrates the relationships between the libraries:

missing library hierarchy image

ObjexxFCL Library

The ObjexxFCL library provides the infrastructure needed to emulate Fortran by code that has been translated from Fortran 77 to C++. It is lightly used in Rosetta at present, having gradually disappeared as Rosetta became more object-oriented - the Rosetta to Rosetta++ to Rosetta3 transition. It remains to support some legacy code.

Utility Library

The utility directory contains utility classes that are (at least in theory) not Rosetta-specific such as utility::vector1 (a base 1 indexed of child class of std::vector with a few extra additions) and izstream (an infilestream which allows reading of zipped files). Broadly speaking, these classes are implemented in a project-agnostic manner (i.e. they need not be Rosetta-specific). Classes in this directory sometimes have mathematical class methods, but algorithms for complicated calculations are better placed in the numeric directory.

Namespaces within utility

Useful classes within utility

Owning pointer
Access pointer
Classes derived from std::vector
- vector0
- vector1
- vectorL
xyzVector
xyzMatrix

Numeric Library

The numeric directory contains low-level functions that carry out mathematical operations. While some of these might be general mathematics (calculating a fast Fourier transform, for example, or performing principal component analysis on a dataset), others might be Rosetta-specific calculations or might be implemented in a Rosetta-specific manner.

Basic Library

The basic directory contains organizational and housekeeping classes specific to the Rosetta project. Functions for accessing the Rosetta database typically reside here, for example, as does code for the Rosetta options system. Certain Rosetta-specific tools, such as the tracer, can also be found in the basic library.

Core Library

missing Core library hierarchy image

The core directory contains classes that manage most of the internal machinery of Rosetta. This includes topics such as chemical representations of models, conformational representations of models, low-level operations on conformations, and energetic evaluation (scoring) of models. The current structure was instituted at a weeklong event XRW1.

Core.1

The only important contents of this library level are the graph classes (graph in the computer science sense).

Core.2

This library contains three important sections:

Chemical

The chemical directory, which contains important classes like ResidueType, is how Rosetta understands the concept of what atoms are in a chemical entity and how the atoms are connected.

Kinematics

The kinematics directory, which contains classes like AtomTree, MoveMap, and FoldTree, is how Rosetta propagates motion through a structure. TODO linky internal coordinate kinematics

Conformation

The Conformation class is what happens when you thread together Residue classes (based on ResidueTypes) according to the kinematics dictated by the AtomTree - basically, a structure!

Core.3

Scoring

Fairly self explanatory: now that Conformation gets us a structure, how do we score it? This contains all the ScoreFunction and all the common terms that go in it, and an Energies object to store the result of a scoring operation.

Pose

Pose, one of the two most important classes in Rosetta, lives here. Pose is the marriage of a Conformation and an Energies object holding its scores.

Core.4

Core.4 is concerned with optimization algorithms - ways to minimize the energy of the pose. optimization contains the "minimizer", which efficiently finds local energy minima. pack contains the packer, which efficiently searches for sequence/rotamer minima for a given backbone. Note the repeated use of efficiently: this code is tightly integrated with other core classes for speed!

Core.5

This library contains several items, the most important of which is the init machinery that initializes each run of Rosetta (reads the options from command line, sets up the random number generator, etc.)

Documentation by namespace (incomplete)

core::chemical
core::conformation
- core::conformation::idealization NO LONGER EXISTS
core::io::pdb
core::scoring

Readmes, Tutorials and Reference Documents for the Core Library

For a general overview of Rosetta concepts (including many concepts from core), please see the Rosetta overview page.

chemical
- Description of chemical
conformation
- Description of conformation
- Symmetry
pose
- Brief description of pose
kinematics
- AtomTree overview and concepts
- FoldTree overview and concepts
optimization
- Minimization overview and concepts
pack
scoring

Protocols Library

The protocols directory contains higher level code which makes use of the core directory components to accomplish modeling tasks. The code in this directory should be in a state such that it is usable by a general audience. Developers are expected to provide adequate documentation for all code placed in this directory. One of the main base classes to be aware of is the Mover class. This class is the interface class from which most Rosetta developers inherit when creating new modeling protocols. Most developers will interface with the Rosetta code at this level unless they need to extend the model representation capabilities of Rosetta.

Like the core directory, the protocols directory has been split into several library levels, with code in each level only allowed to depend on the levels below it.

Protocols library organization is controlled by a series of protocols_X.#.src.settings files in src/, where X is a letter and # is a number. The numbers are the dependency level of each library, and the letters arrange similar-level sublibraries into a laterally equivalent group. In other words, libraries at the same number level have the same dependencies, but do not depend on each other: in fact they are forbidden from depending on each other.

When the protocols library was split at XRW2, we were partly trying to institute order, and partly trying to fix a problem. The protocols library (the largest in Rosetta) had grown to the point that linking was very slow, and took more memory in the linking step (>2GB, remember this was a while ago) than many developers' computers had. Ultimately, the former goal of organization proved elusive or impossible, but we met the second goal by splitting the previously monolithic protocols into many libraries. As a consequence, to a great degree, the organization is only by fiat. This page documents decisions made at the time. The description of the library levels is much deeper than here, but only partial.

If you are trying to determine "where your code goes", and there isn't a good answer below, the answer is "find something similar and put it in the same sublibrary", so long as the dependencies are otherwise legal (only pointing to lower numbers). Lateral dependencies within a sublibrary are legal.

Important Protocols library levels:

Protocols.1

Lots of goodies live here, including the job distributor, the base class Mover and some of the simple Movers, the base class Filter and simple Filters, the RosettaScripts machinery.

Protocols.2

Your code should almost certainly not go here.

Protocols.3

This level contains the vast majority of Movers and Filters that do simple things (as opposed to complex or highly specific Movers that live with their protocol directly). It also contains loops machinery and toolbox, which holds lots of generic tools for detecting and manipulating classes or groups of residues (think interface-detection machinery, etc).

Protocols.4-6

These levels each have many lettered sublibaries, organized by vague similarity and number of files, but it's kind of a mess. I'm sorry I can't help more.

Protocols.7

This is not a library, this is just the protocols init layer. It has a ton of Registrators and Creators for the Factory (wikipedia link)-managed Rosetta classes.

Devel Library

The devel directory is a staging area for protocols in development, which is NOT included in Rosetta releases. Code in this area is not considered mature. Standards of documentation are lax. Documenting code after the fact is much more difficult, so it is HIGHLY recommended that a developer provide good documentation even for code that is fluctuating rapidly. It will make your life easier and more productive, and your colleagues will appreciate your thoroughness.

Adding new code or subdirectories

Generally one will not want to add code in src directly.
New subdirectories in one of the above existing directories can be added much more readily without damaging the overall structure of the library. First determine which level of the library the new concepts fit into. If one is unsure of where new code should be placed, consult experienced Rosetta developers. This can either be in one's lab or (even better) send a message out to the developer mailing list (One might find out that someone else has a complimentary idea with a starting point already available).