Macros to aid with implementation classes

---

Detailed Description

These macros are here to aid with implementing classes that inherit from the various abstract base classes in the kernel. Each macro, which should be used in the body of the class, declares/defines the set of needed functions. The declared functions should be defined in the associated .cpp file. By using the macros, you ensure that your class gets the names of the functions correct and it makes it easier to update your class if the functions should change.

All of the macros define the following methods:

• IMP::Object::get_version_info()
• an empty virtual destructor

In addition, they all declare:

• IMP::Object::do_show()

For all macros, the Name parameter is the name of the class being implemented and the version_info parameter is the IMP::VersionInfo to use (probably get_version_info()).

Defines
#define	IMP_CONSTRAINT(Name)
	Define the basics needed for a ScoreState.
#define	IMP_FAILURE_HANDLER(Name)
	Declare a IMP::FailureHandler.
#define	IMP_INCREMENTAL_RESTRAINT(Name)
	Define the basic things you need for a Restraint.
#define	IMP_INTERNAL_OBJECT(Name)
	Define the basic things needed by any internal Object.
#define	IMP_INTERNAL_SINGLETON_MODIFIER(Name,apply_expr)
	Define a simple SingletonModifier.
#define	IMP_OBJECT(Name)
	Define the basic things needed by any Object.
#define	IMP_OBJECT_INLINE(Name, show, destructor)
	Define the basic things needed by any Object.
	IMP::Optimizer::IMP_OPTIMIZER(Name)
	Define the basic things you need for an Optimizer.
#define	IMP_OPTIMIZER(Name)
	Define the basic things you need for an Optimizer.
#define	IMP_OPTIMIZER_STATE(Name)
	Define the basics needed for an OptimizerState.
#define	IMP_PAIR_CONTAINER(Name)
	Declare the needed functions for a PairContainer.
#define	IMP_PAIR_FILTER(Name)
	Declare the needed functions for a PairFilter.
#define	IMP_PAIR_MODIFIER(Name)
	Declare the functions needed for a PairModifier.
#define	IMP_PAIR_MODIFIER_DA(Name)
	Declare the functions needed for a PairModifier.
#define	IMP_PAIR_SCORE(Name)
	Declare the functions needed for a PairScore.
#define	IMP_PERIODIC_OPTIMIZER_STATE(Name)
	Define the basics needed for an OptimizerState which acts every n steps.
#define	IMP_QUAD_CONTAINER(Name)
	Declare the needed functions for a QuadContainer.
#define	IMP_QUAD_FILTER(Name)
	Declare the needed functions for a QuadFilter.
#define	IMP_QUAD_SCORE(Name)
	Declare the functions needed for a QuadScore.
#define	IMP_RAII(Name, args, Initialize, Set, Reset)
	Declare a RAII-style class.
#define	IMP_REFINER(Name)
	Define the basics needed for a particle refiner.
#define	IMP_RESTRAINT(Name)
	Define the basic things you need for a Restraint.
	IMP::Sampler::IMP_SAMPLER(Name)
	Define the basic things you need for a Sampler.
#define	IMP_SAMPLER(Name)
	Define the basic things you need for a Sampler.
#define	IMP_SCORE_STATE(Name)
	Define the basics needed for a ScoreState.
#define	IMP_SIMPLE_PAIR_SCORE(Name)
	Declare the functions needed for a SingletonScore.
#define	IMP_SIMPLE_REFINER(Name)
	Define the basics needed for a particle refiner.
#define	IMP_SIMPLE_SINGLETON_SCORE(Name)
	Declare the functions needed for a SingletonScore.
#define	IMP_SIMPLE_TRIPLET_SCORE(Name)
	Declare the functions needed for a TripletScore.
#define	IMP_SINGLETON_CONTAINER(Name)
	Declare the needed functions for a SingletonContainer.
#define	IMP_SINGLETON_FILTER(Name)
	Declare the needed functions for a SingletonFilter.
#define	IMP_SINGLETON_MODIFIER(Name)
	Declare the functions needed for a SingletonModifier.
#define	IMP_SINGLETON_MODIFIER_DA(Name)
	Declare the functions needed for a SingletonModifier.
#define	IMP_SINGLETON_MODIFIER_FROM_REFINED(Name, refiner)
	Add interaction methods to a SingletonModifer.
#define	IMP_SINGLETON_MODIFIER_TO_REFINED(Name, refiner)
	Add interaction methods to a SingletonModifer.
#define	IMP_SINGLETON_SCORE(Name)
	Declare the functions needed for a SingletonScore.
#define	IMP_TRIPLET_CONTAINER(Name)
	Declare the needed functions for a TripletContainer.
#define	IMP_TRIPLET_FILTER(Name)
	Declare the needed functions for a TripletFilter.
#define	IMP_TRIPLET_SCORE(Name)
	Declare the functions needed for a TripletScore.
#define	IMP_UNARY_FUNCTION(Name)
	Declare the needed functions for a UnaryFunction.
#define	IMP_UNARY_FUNCTION_INLINE(Name, value_expression,derivative_expression, show_expression)
	Declare the needed functions for a UnaryFunction which evaluates inline.

---

Define Documentation

#define IMP_CONSTRAINT

(

Name

)

Define the basics needed for a ScoreState.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::Constraint::do_update_attributes()
• IMP::Constraint::do_update_derivatives()

#define IMP_FAILURE_HANDLER

(

Name

)

Value:

void handle_failure();                        \
  IMP_OBJECT(Name)

Declare a IMP::FailureHandler.

In addition to the standard methods it declares:

• IMP::FailureHandler::handle_failure()

#define IMP_INCREMENTAL_RESTRAINT

(

Name

)

Define the basic things you need for a Restraint.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::Restraint::unprotected_evaluate()
• IMP::Restraint::unprotected_incremental_evaluate()
• IMP::Restraint::get_input_containers()
• IMP::Restraint::get_interacting_particles()
• IMP::Restraint::get_input_particles()

and it defines

• IMP::Restraint::get_is_incremental() to return true

#define IMP_INTERNAL_OBJECT

(

Name

)

Define the basic things needed by any internal Object.

See also:

IMP_OBJECT This version also defines IMP::Object::do_show()

#define IMP_INTERNAL_SINGLETON_MODIFIER	(	Name,
		apply_expr		)

Define a simple SingletonModifier.

In addition to the methods done by IMP_OBJECT, it defines

• IMP::SingletonModifier::apply(IMP::Particle*) to the provided value
• IMP::SingletonModifier::get_interacting_particles() to return None
• IMP::SingletonModifier::get_input_particles() to return the particle
• IMP::SingletonModifier::get_output_particles() to return the particle
• IMP::Object::do_show() This macro should only be used to define types which are used internally in algorithms and data structures.

  See also:

  IMP_SINGLETON_MODIFIER_DA

  IMP_SINGLETON_MODIFIER

#define IMP_OBJECT

(

Name

)

Define the basic things needed by any Object.

This defines

• IMP::Object::get_version_info()
• a private destructor and declares
• IMP::Object::do_show()

#define IMP_OBJECT_INLINE	(	Name,
		show,
		destructor		)

Define the basic things needed by any Object.

This defines

• IMP::Object::get_version_info()
• a private destructor and declares
• IMP::Object::do_show()

IMP_OPTIMIZER

(

Name

)

[related, inherited]

Define the basic things you need for an Optimizer.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::Optimizer::optimize()

#define IMP_OPTIMIZER

(

Name

)

Value:

virtual Float optimize(unsigned int max_steps);       \
  IMP_OBJECT(Name);

Define the basic things you need for an Optimizer.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::Optimizer::optimize()

#define IMP_OPTIMIZER_STATE

(

Name

)

Value:

virtual void update();                        \
  IMP_OBJECT(Name);

Define the basics needed for an OptimizerState.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::OptimizerState::update()

#define IMP_PAIR_CONTAINER

(

Name

)

Declare the needed functions for a PairContainer.

In addition to the methods of IMP_OBJECT, it declares

• IMP::PairContainer::get_contains_particle_pair()
• IMP::PairContainer::get_number_of_particle_pairs()
• IMP::PairContainer::get_particle_pair()
• IMP::PairContainer::apply()
• IMP::PairContainer::evaluate()
• IMP::Interaction::get_input_objects()

#define IMP_PAIR_FILTER

(

Name

)

Declare the needed functions for a PairFilter.

In addition to the methods done by all the macros, it declares

• IMP::PairFilter::get_contains_particle_pair()
• IMP::PairFilter::get_input_particles()

#define IMP_PAIR_MODIFIER

(

Name

)

Declare the functions needed for a PairModifier.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::PairModifier::apply(IMP::Particle*,IMP::Particle*)
• IMP::PairModifier::get_interacting_particles()
• IMP::PairModifier::get_input_particles()
• IMP::PairModifier::get_output_particles()

  See also:

  IMP_PAIR_MODIFIER_DA

#define IMP_PAIR_MODIFIER_DA

(

Name

)

Declare the functions needed for a PairModifier.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::PairModifier::apply(Particle*,Particle*,DerivativeAccumulator&)
• IMP::PairModifier::get_interacting_particles()
• IMP::PairModifier::get_input_particles()
• IMP::PairModifier::get_output_particles()

  See also:

  IMP_PAIR_MODIFIER

#define IMP_PAIR_SCORE

(

Name

)

Declare the functions needed for a PairScore.

In addition to the methods done by IMP_OBJECT(), it declares

• IMP::PairScore::evaluate()
• IMP::PairScore::get_interacting_particles()
• IMP::PairScore::get_input_particles()
• IMP::PairScore::get_output_particles()
• IMP::PairScore::get_is_changed()

The macro expects a class method

• bool get_is_changed(const ParticlePair&) which returns true if the score needs to be recalculated.

See IMP_SIMPLE_PAIR_SCORE() for a way of providing an implementation of that method.

#define IMP_PERIODIC_OPTIMIZER_STATE

(

Name

)

Define the basics needed for an OptimizerState which acts every n steps.

In addition to the methods done by all the macros, it declares

• do_update(unsigned int call_number) where step number is the number of the optimization step, and call_number is the number of the call to do_update. It also defines
• void set_skip_steps(unsigned int)

If you use this macro, you should also include IMP/internal/utility.h.

#define IMP_QUAD_CONTAINER

(

Name

)

Declare the needed functions for a QuadContainer.

In addition to the methods of IMP_OBJECT, it declares

• IMP::QuadContainer::get_contains_particle_quad()
• IMP::QuadContainer::get_number_of_particle_quads()
• IMP::QuadContainer::get_particle_quad()
• IMP::QuadContainer::apply()
• IMP::QuadContainer::evaluate()
• IMP::Interaction::get_input_objects()

#define IMP_QUAD_FILTER

(

Name

)

Declare the needed functions for a QuadFilter.

In addition to the methods done by all the macros, it declares

• IMP::QuadFilter::get_contains_particle_quad()
• IMP::QuadFilter::get_input_particles()

#define IMP_QUAD_SCORE

(

Name

)

Declare the functions needed for a QuadScore.

In addition to the methods done by IMP_OBJECT(), it declares

• IMP::QuadScore::evaluate()
• IMP::QuadScore::get_interacting_particles()
• IMP::QuadScore::get_input_particles()
• IMP::QuadScore::get_output_particles()

The macro expects a class method

• bool get_is_changed(ParticleQuad) which returns true if the score needs to be recalculated.

#define IMP_RAII	(	Name,
		args,
		Initialize,
		Set,
		Reset		)

Declare a RAII-style class.

Since such classes are typically quite small and simple, all the implementation is inline. The macro declares

• default constructor
• RAII::set()
• RAII::reset()
• destructor The Set and Reset arguments are the code to run in the respective functions. "args" are the argument string (in parens) for the constructor and set.

#define IMP_REFINER

(

Name

)

Define the basics needed for a particle refiner.

In addition to the methods done by all the macros, it declares

• IMP::Refiner::get_can_refine()
• IMP::Refiner::get_number_of_refined()
• IMP::Refiner::get_refined()
• IMP::Refiner::get_input_particles()

  See also:

  IMP_SIMPLE_REFINER

#define IMP_RESTRAINT

(

Name

)

Define the basic things you need for a Restraint.

In addition to the methods defined by IMP::Object it declares

• IMP::Restraint::unprotected_evaluate()
• IMP::Restraint::get_input_containers()
• IMP::Restraint::get_interacting_particles()
• IMP::Restraint::get_input_particles()

It also defines

• IMP::Restraint::get_is_incremental() to return 0
• IMP::Restraint::incremental_evaluate() to throw an exception

IMP_SAMPLER

(

Name

)

[related, inherited]

Define the basic things you need for a Sampler.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::Sampler::do_sample()

#define IMP_SAMPLER

(

Name

)

Value:

IMP_OBJECT(Name);                             \
protected:                                      \
 ConfigurationSet* do_sample() const;

Define the basic things you need for a Sampler.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::Sampler::do_sample()

#define IMP_SCORE_STATE

(

Name

)

Define the basics needed for a ScoreState.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::ScoreState::do_before_evaluate()
• IMP::ScoreState::do_after_evaluate()
• IMP::ScoreState::get_input_containers()
• IMP::ScoreState::get_output_containers()
• IMP::ScoreState::get_input_particles()
• IMP::ScoreState::get_output_particles()

#define IMP_SIMPLE_PAIR_SCORE

(

Name

)

Declare the functions needed for a SingletonScore.

In addition to the methods declared and defined by IMP_PAIR_SCORE, the macro provides an implementation of

• IMP::PairScore::get_is_changed()
• IMP::PairScore::get_interacting_particles()
• IMP::PairScore::get_input_particles()
• IMP::PairScore::get_input_containers() which assume that only the 2 passed particles serve as inputs to the score.

#define IMP_SIMPLE_REFINER

(

Name

)

Define the basics needed for a particle refiner.

In contrast to IMP_REFINER, if this macro is used, the Refiner::get_refined(Particle*) method is implemented using the other Refiner::get_refined() method and so does not have to be provided.

See also:

IMP_REFINER

#define IMP_SIMPLE_SINGLETON_SCORE

(

Name

)

Declare the functions needed for a SingletonScore.

In addition to the methods declared and defined by IMP_SINGLETON_SCORE, the macro provides an implementation of

• IMP::SingletonScore::get_is_changed()
• IMP::SingletonScore::get_interacting_particles()
• IMP::SingletonScore::get_input_particles()
• IMP::SingletonScore::get_input_containers() which assume that only the passed particle serves as input to the score.

#define IMP_SIMPLE_TRIPLET_SCORE

(

Name

)

Declare the functions needed for a TripletScore.

In addition to the methods declared and defined by IMP_TRIPLET_SCORE, the macro provides an implementation of

• IMP::TripletScore::get_is_changed()
• IMP::TripletScore::get_interacting_particles()
• IMP::TripletScore::get_input_particles()
• IMP::TripletScore::get_input_containers() which assume that only the 3 passed particles serve as inputs to the score.

#define IMP_SINGLETON_CONTAINER

(

Name

)

Declare the needed functions for a SingletonContainer.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::SingletonContainer::get_contains_particle()
• IMP::SingletonContainer::get_number_of_particles()
• IMP::SingletonContainer::get_particle()
• IMP::SingletonContainer::apply()
• IMP::SingletonContainer::evaluate()
• IMP::Interaction::get_input_objects()

#define IMP_SINGLETON_FILTER

(

Name

)

Declare the needed functions for a SingletonFilter.

In addition to the methods done by all the macros, it declares

• IMP::SingletonFilter::get_contains_particle()
• IMP::SingletonFilter::get_input_particles()

#define IMP_SINGLETON_MODIFIER

(

Name

)

Declare the functions needed for a SingletonModifier.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::SingletonModifier::apply(IMP::Particle*)
• IMP::SingletonModifier::get_interacting_particles()
• IMP::SingletonModifier::get_input_particles()
• IMP::SingletonModifier::get_output_particles()

  See also:

  IMP_SINGLETON_MODIFIER_DA

#define IMP_SINGLETON_MODIFIER_DA

(

Name

)

Declare the functions needed for a SingletonModifier.

In addition to the methods done by IMP_OBJECT, it declares

• IMP::SingletonModifier::apply(IMP::Particle*, IMP::DerivativeAccumulator&)
• IMP::SingletonModifier::get_interacting_particles()
• IMP::SingletonModifier::get_input_particles()
• IMP::SingletonModifier::get_output_particles()

See also:

IMP_SINGLETON_MODIFIER

#define IMP_SINGLETON_MODIFIER_FROM_REFINED	(	Name,
		refiner		)

Add interaction methods to a SingletonModifer.

This macro is designed to be used in conjunction with IMP_SINGLETON_MODIFIER or IMP_SINGLETON_MODIFIER_DA. It adds definitions for the methods:

• IMP::SingletonModifier::get_interacting_particles()
• IMP::SingletonModifier::get_input_particles()
• IMP::SingletonModifier::get_output_particles() for a modifier which updates the passed particle based on the results of refinement.

#define IMP_SINGLETON_MODIFIER_TO_REFINED	(	Name,
		refiner		)

Add interaction methods to a SingletonModifer.

This macro is designed to be used in conjunction with IMP_SINGLETON_MODIFIER or IMP_SINGLETON_MODIFIER_DA. It adds definitions for the methods:

• IMP::SingletonModifier::get_interacting_particles()
• IMP::SingletonModifier::get_input_particles()
• IMP::SingletonModifier::get_output_particles()
• IMP::Object::do_show() for a modifier which updates the refined particles based on the one they are refined from.

This macro should appear in a .cpp file.

#define IMP_SINGLETON_SCORE

(

Name

)

Declare the functions needed for a SingletonScore.

In addition to the methods done by IMP_INTERACTON, it declares

• IMP::SingletonScore::evaluate(IMP::Particle*, IMP::DerivativeAccumulator*)
• IMP::SingletonScore::get_interacting_particles() IMP::DerivativeAccumulator*)
• IMP::SingletonScore::get_input_particles()
• IMP::SingletonScore::get_is_changed()
• IMP::SingletonScore::get_output_particles()

The macro expects a class method

• bool get_is_changed(Particle*) which returns true if the score needs to be recalculated.

See IMP_SIMPLE_SINGLETON_SCORE() for a way of providing an implementation of that method.

#define IMP_TRIPLET_CONTAINER

(

Name

)

Declare the needed functions for a TripletContainer.

In addition to the methods of IMP_OBJECT, it declares

• IMP::TripletContainer::get_contains_particle_triplet()
• IMP::TripletContainer::get_number_of_particle_triplets()
• IMP::TripletContainer::get_particle_triplet()
• IMP::TripletContainer::apply()
• IMP::TripletContainer::evaluate()
• IMP::Interaction::get_input_objects()

#define IMP_TRIPLET_FILTER

(

Name

)

Declare the needed functions for a TripletFilter.

In addition to the methods done by all the macros, it declares

• IMP::TripletFilter::get_contains_particle_triplet()
• IMP::TripletFilter::get_input_particles()

#define IMP_TRIPLET_SCORE

(

Name

)

Declare the functions needed for a TripletScore.

In addition to the methods done by IMP_OBJECT(), it declares

• IMP::TripletScore::evaluate()
• IMP::TripletScore::get_is_changed()
• IMP::TripletScore::get_interacting_particles()
• IMP::TripletScore::get_input_particles()
• IMP::TripletScore::get_output_particles()

The macro expects a class method

• bool get_is_changed(ParticleTriplet) which returns true if the score needs to be recalculated.

See IMP_SIMPLE_TRIPLET_SCORE() for a way of providing an implementation of that method.

#define IMP_UNARY_FUNCTION

(

Name

)

Value:

virtual DerivativePair evaluate_with_derivative(double feature) const; \
  virtual double evaluate(double feature) const;                        \
  IMP_OBJECT(Name)

Declare the needed functions for a UnaryFunction.

In addition to the methods done by all the macros, it declares

• IMP::UnaryFunction::evaluate()
• IMP::UnaryFunction::evaluate_with_derivatives()

See also:

IMP_UNARY_FUNCTION_INLINE

#define IMP_UNARY_FUNCTION_INLINE	(	Name,
		value_expression,
		derivative_expression,
		show_expression		)

Declare the needed functions for a UnaryFunction which evaluates inline.

This macro declares all the functions needed for an IMP::UnaryFunction inline in the class. There is no need for an associated .cpp file.

The last three arguments are expressions that evaluate to the unary function value and derivative and are sent to the stream in the show function, respectively. The input to the function is called feature.

See also:

IMP_UNARY_FUNCTION