RosettaScripts Developer Guide

This page was modified in the Minicon 11 Wiki Update, but we didn't quite finish it for reasons of lack of time or knowledge. If you can finish it, please do!

Using RosettaScripts in its most basic sense involves organizing a workflow of Mover classes that are defined and parameterized in an XML-like scripting language that is read and processed into an arbitrary minirosetta protocol at runtime. The use of Filter classes is also used to further control protocol flow.

DataMap

The DataMap is an internal structure for holding pointers to objects of arbitrary type. Each Mover's parse_my_tag() method has const access to the DataMap, and can recover pointers from it. This can be useful for communication between movers. For example, both the LoopFinder and KinematicLoop movers can get a common LoopsOP during parsing. At apply time the LoopFinder can fill the LoopsOP with loops, and KinematicLoop can subsequently read from it.

Movers

Mover Requirements

In order to be supported under the Parser scheme, a Mover class (any class that derives from the Mover base class) must implement some additional methods. (These are virtual methods of the Mover base class that to be overwritten in the derived class.)

Note that the function signatures for parse_my_tag and the other functions should match the ones from the Mover base class exactly (including const status), otherwise the derived method will not be called.

Getting Parameter data

The parse_my_tag function can obtain passed parameters through the passed TagPtr object. Two functions are relevant:

Score Functions

Obtaining the scorefunction is of particular note. The name specified for a score function parameter can be obtained via:

Reference to the score function object itself can then obtained through the DataMap:

Alternatively, one can use the parse_score_function() convenience function in protocols/RosettaScripts/util.hh

Task Objects

If your mover takes as input a packer task, you likely want to observe the directives in the <TASKOPERATIONS> section of the XML file. (See TaskOperations (RosettaScripts).)

A parse_task_operations() convenience function is provided for this purpose in protocols/RosettaScripts/util.hh. It parses the Tag pointer and Datamap appropriately, and returns an owning pointer to an appropriately constructed TaskFactory object.

Registering Movers with the Parser

Previously, movers needed to pass a unique name string to its parent's constructor in order to get correctly registered with the mover constructing machinery. This is no longer necessary.

The current registration is thorough MoverCreators, subclasses of protocols::moves::MoverCreator with three member functions (MoverCreators should be defined in a separate header file, but implementation of these functions is usually placed in the same .cc file as the mover):

An existing MoverCreator (such as GenericMonteCarloMoverCreator) can be used as reference, but briefly, create_mover() returns a pointer to a new instance of the corresponding Mover, mover_name() should returns the unique string which identifies the mover in the XML file, and keyname() calls and passes through the return value of mover_name().

Finally, src/protocols/init.cc (or equivalent, if the mover is not under src/protocols) should be edited to add the new MoverCreator to the list of other MoverCreators. References to the Mover itself or the Mover's header file should not be present in init.cc - only the lightweight MoverCreator (and corresponding minimal header file) should be referenced.

Filters

Requirements are all the same as of Mover, with one exception that the Pose object passed to apply() is non-mutable. The method shall return true when the pose passes a filtering test, and false otherwise.

TaskOperations

TaskOperations that are specified in utility::Tag scripts in order to be utilized by Movers require careful (but relatively simple) implementation of virtual functions, a Creator class, and load-time registration in an init.cc file.

As of trunk revisions r34048, r34052, and r34063, DockDesignParser no longer owns its own TaskOperationFactory. There is now a singleton factory that lives at core::pack::task::operation::TaskOperationFactory. Also, protocols no longer need to manually register TaskOperations with this factory. Instead, TaskOperations are registered with the factory at "init" time (core/init.cc,protocols/init.cc,devel/init.cc) via Creator and Registrator classes. Creators are helper classes that make the TaskOperationFactory aware of how to create different flavors of TaskOperations. This way the TaskOperationFactory can store very-low-weight Creator classes, and only makes specific actual TaskOperations upon demand. This saves time, memory, and I/O. See the core/pack/task/operation/ directory and protocols/init.cc for examples of how these classes are implemented and cooperate.

"protocols" TaskOperations live in src/protocols and should be registered in protocols/init.cc (not in core). Some very general classes may be placed in core/pack/task/operation/, but this should only be done if they are widely used and do not introduce significant new dependencies into the core::pack namespace. Also, do not directly register or include headers for derived classes in any Factory classes.

These same principle apply to ResFilter and ResLvlTaskOperation classes, which are implemented in the same way TaskOperations.

TaskOperations may implement their own parse_tag method to parse user-defined options.

THIS PAGE UNDER CONSTRUCTION

and subject to significant change due to current refactoring