colvardeps.h

// -*- c++ -*-
 
// This file is part of the Collective Variables module (Colvars).
// The original version of Colvars and its updates are located at:
// https://github.com/Colvars/colvars
// Please update all Colvars source files before making any changes.
// If you wish to distribute your changes, please submit them to the
// Colvars repository at GitHub.
 
#ifndef COLVARDEPS_H
#define COLVARDEPS_H
 
#include "colvarmodule.h"
#include "colvarparse.h"
 
class colvardeps {
public:
 
  colvardeps();
  virtual ~colvardeps();
 
  // Subclasses should initialize the following members:
 
  std::string description; // reference to object name (cv, cvc etc.)
 
  // since the feature class only contains static properties
  struct feature_state {
    feature_state(bool a, bool e)
    : available(a), enabled(e), ref_count(0) {}
 
    bool available;
    bool enabled;     // see if this should be private depending on implementation
 
    // bool enabledOnce; // this should trigger an update when object is evaluated
 
    int ref_count;
    std::vector<int> alternate_refs;
  };
 
protected:
  int   time_step_factor;
 
  std::vector<feature_state> feature_states;
 
  enum feature_type {
    f_type_not_set,
    f_type_dynamic,
    f_type_user,
    f_type_static
  };
 
public:
  inline int get_time_step_factor() const {return time_step_factor;}
 
  void init_feature(int feature_id, const char *description, feature_type type);
 
  class feature {
 
  public:
    feature() : type(f_type_not_set) {}
    ~feature() {}
 
    std::string description; // Set by derived object initializer
 
    // features that this feature requires in the same object
    // NOTE: we have no safety mechanism against circular dependencies, however, they would have to be internal to an object (ie. requires_self or requires_alt)
    std::vector<int> requires_self;
 
    // Features that are incompatible, ie. required disabled
    // if enabled, they will cause a dependency failure (they will not be disabled)
    // To enforce these dependencies regardless of the order in which they
    // are enabled, they are always set in a symmetric way, so whichever is enabled
    // second will cause the dependency to fail
    std::vector<int> requires_exclude;
 
    // sets of features that are required in an alternate way
    // when parent feature is enabled, if none are enabled, the first one listed that is available will be enabled
    std::vector<std::vector<int> > requires_alt;
 
    // features that this feature requires in children
    std::vector<int> requires_children;
 
    inline bool is_dynamic() { return type == f_type_dynamic; }
    inline bool is_static() { return type == f_type_static; }
    inline bool is_user() { return type == f_type_user; }
    feature_type type;
  };
 
  inline bool is_not_set(int id) { return features()[id]->type == f_type_not_set; }
  inline bool is_dynamic(int id) { return features()[id]->type == f_type_dynamic; }
  inline bool is_static(int id) { return features()[id]->type == f_type_static; }
  inline bool is_user(int id) { return features()[id]->type == f_type_user; }
 
  // Accessor to array of all features with deps, static in most derived classes
  // Subclasses with dynamic dependency trees may override this
  // with a non-static array
  // Intermediate classes (colvarbias and colvarcomp, which are also base classes)
  // implement this as virtual to allow overriding
  virtual const std::vector<feature *> &features() const = 0;
  virtual std::vector<feature *>&modify_features() = 0;
 
  void add_child(colvardeps *child);
 
  void remove_child(colvardeps *child);
 
  void remove_all_children();
 
private:
 
  std::vector<colvardeps *> children;
 
  std::vector<colvardeps *> parents;
 
public:
  // Checks whether given feature is enabled
  // Defaults to querying f_*_active
  inline bool is_enabled(int f = f_cv_active) const {
    return feature_states[f].enabled;
  }
 
  // Checks whether given feature is available
  // Defaults to querying f_*_active
  inline bool is_available(int f = f_cv_active) const {
    return feature_states[f].available;
  }
 
  void provide(int feature_id, bool truefalse = true);
 
  void set_enabled(int feature_id, bool truefalse = true);
 
protected:
 
  bool get_keyval_feature(colvarparse *cvp,
                          std::string const &conf, char const *key,
                          int feature_id, bool const &def_value,
                          colvarparse::Parse_Mode const parse_mode = colvarparse::parse_normal);
 
public:
 
  int enable(int f, bool dry_run = false, bool toplevel = true);
 
  int disable(int f);
 
  void free_children_deps();
 
  void restore_children_deps();
 
  int decr_ref_count(int f);
 
  virtual void do_feature_side_effects(int /* id */) {}
 
  // NOTE that all feature enums should start with f_*_active
  enum features_biases {
    f_cvb_active,
    f_cvb_awake,
    f_cvb_step_zero_data,
    f_cvb_apply_force,
    f_cvb_bypass_ext_lagrangian,
    f_cvb_get_total_force,
    f_cvb_output_acc_work,
    f_cvb_history_dependent,
    f_cvb_time_dependent,
    f_cvb_scalar_variables,
    f_cvb_calc_pmf,
    f_cvb_calc_ti_samples,
    f_cvb_write_ti_samples,
    f_cvb_write_ti_pmf,
    f_cvb_scale_biasing_force,
    f_cvb_extended,
    f_cvb_ntot
  };
 
  enum features_colvar {
    f_cv_active,
    f_cv_awake,
    f_cv_gradient,
    f_cv_collect_gradient,
    f_cv_collect_atom_ids,
    f_cv_fdiff_velocity,
    f_cv_total_force,
    f_cv_total_force_calc,
    f_cv_subtract_applied_force,
    f_cv_Jacobian,
    f_cv_hide_Jacobian,
    f_cv_extended_Lagrangian,
    f_cv_external,
    f_cv_Langevin,
    f_cv_output_energy,
    f_cv_output_value,
    f_cv_output_velocity,
    f_cv_output_applied_force,
    f_cv_output_total_force,
    f_cv_lower_boundary,
    f_cv_upper_boundary,
    f_cv_hard_lower_boundary,
    f_cv_hard_upper_boundary,
    f_cv_reflecting_lower_boundary,
    f_cv_reflecting_upper_boundary,
    f_cv_grid,
    f_cv_runave,
    f_cv_corrfunc,
    f_cv_scripted,
    f_cv_custom_function,
    f_cv_periodic,
    f_cv_single_cvc,
    f_cv_scalar,
    f_cv_linear,
    f_cv_homogeneous,
    f_cv_multiple_ts,
    f_cv_ntot
  };
 
  enum features_cvc {
    f_cvc_active,
    f_cvc_scalar,
    f_cvc_periodic,
    f_cvc_width,
    f_cvc_lower_boundary,
    f_cvc_upper_boundary,
    f_cvc_explicit_atom_groups,
    f_cvc_gradient,
    f_cvc_explicit_gradient,
    f_cvc_inv_gradient,
    f_cvc_Jacobian,
    f_cvc_one_site_total_force,
    f_cvc_debug_gradient,
    f_cvc_pbc_minimum_image,
    f_cvc_com_based,
    f_cvc_scalable,
    f_cvc_scalable_com,
    f_cvc_collect_atom_ids,
    f_cvc_ntot
  };
 
  enum features_atomgroup {
    f_ag_active,
    f_ag_center,
    f_ag_center_origin,
    f_ag_rotate,
    f_ag_fitting_group,
//     f_ag_min_msd_fit,
    f_ag_explicit_gradient,
    f_ag_fit_gradients,
    f_ag_atom_forces,
    f_ag_scalable,
    f_ag_scalable_com,
    f_ag_collect_atom_ids,
    f_ag_ntot
  };
 
  virtual int init_dependencies() = 0;
 
  void require_feature_self(int f, int g);
 
  void exclude_feature_self(int f, int g);
 
  void require_feature_children(int f, int g);
 
  void require_feature_alt(int f, int g, int h);
 
  void require_feature_alt(int f, int g, int h, int i);
 
  void require_feature_alt(int f, int g, int h, int i, int j);
 
  void print_state();
 
  inline void check_enabled(int f, std::string const &reason) const
  {
    if (! is_enabled(f)) {
      cvm::error("Error: "+reason+" requires that the feature \""+
                 features()[f]->description+"\" is active.\n", COLVARS_BUG_ERROR);
    }
  }
 
};
 
#endif