added notes and some drafty interface

src/Interface/hiopInterface.hpp

@@ -467,8 +467,8 @@ class hiopInterfaceBase
   }
 
   /** 
-   * This method is used to provide an user all the hiop iterate
-   * procedure. @see solution_callback() for an explanation of the parameters.
+   * This method is used to provide user all the internal hiop iterates. @see solution_callback() 
+   * for an explanation of the parameters.
    * 
    * @param[in] x array of (local) entries of the primal variables (managed by Umpire, see note below)
    * @param[in] z_L array of (local) entries of the dual variables for lower bounds (managed by Umpire, see note below)
@@ -497,6 +497,25 @@ class hiopInterfaceBase
     return true;
   }
 
+  /**
+   * This method is called after each iteration and should be implemented by the user to instruct HiOp 
+   * to save a complete state of the algorithm to disk. An axom::sidre::DataStore will be used for IO, which 
+   * can be set by the user upon creation of the HiOp algorithm class. If not set, HiOp will used one.
+   * 
+   * This is feature is useful for IO checkpointing, for example; it allows the internal algorithm to be 
+   * restarted at the same state as before saving. @see hiop::hiopAlgorithm::tbd for the method to be used 
+   * to load a previously saved state.
+   * 
+   * The method provided by the user should return true if HiOp should save the state of the algorithm at
+   * at current iteration. The argument is passed by HiOp to indicate the current iterate number.
+   *
+   *  @param[in] iter the current iteration number
+   */
+  virtual bool save_state_iterate_callback(int iter)
+  {
+    return false;
+  }
+
   /**
    * A wildcard function used to change the primal variables.
    *

src/Optimization/hiopAlgFilterIPM.hpp

@@ -117,6 +117,75 @@ class hiopAlgFilterIPMBase {
   { 
     return filter.contains(theta, logbar_obj); 
   }
+
+  //notes on checkpointing
+  // 1. need to allow user to pass axom::sidre::DataStore. HiOp will put all the info into a group
+  //  Question: should a DataStore be passed any time restarting is invoked (this is a bit cumbersome),
+  //            or just once, by calling the HiOp algorithm class
+  //
+  //  
+  //
+  //
+  // (for when checkpointing is used without the user setting a data store, so HiOp will create it and do the IO)
+  // 2. need to allow user to pass a string with the file where the DataStore will be
+  // writting to/reading from. A default name will be used for empty filename.
+
+  /**
+   * Setter for the axom::sidre DataStore used to manage the data associated with the state of 
+   * NLP the algorithm. If the setter is not called by the user, the DataStore will be created
+   * internally by the iteration checkpointing object.
+   */
+  inline void set_state_data_manager(axom::sidre::DataStore& mng)
+  {
+    iter_chkpnt_.set_data_manger(mng);
+  }
+
+  /**
+   * The method saves the state of the algorithm in the axom::sidre::DataStore object that was
+   * previously provided by @set_checkpoint_data_manager. If this method has not been previously
+   * called, the HiOp will create such instance and will save it on disk under a default name.
+   */
+  inline void save_state()
+  {
+    iter_chkpnt_.save(this);
+  }
+
+  /**
+   * The method saves the state of the algorithm in the file specified by the string argument. If
+   * the string is empty, a file with a default name will be created. 
+   * 
+   * Internally, HiOp uses axom::sidre::DataStore object that is created internally and shares the 
+   * IO code with @save_state. This method disregards previous calls to @set_checkpoint_data_manager. 
+   */
+  inline void save_state(const std::string& filename)
+  {
+    iter_chkpnt_.save(filename, this);
+  }
+
+
+  /**
+   * This method loads the state of the algorithm from a axom::sidre::DataStore that was previously 
+   * provided by @set_checkpoint_data_manager. This DataStore instance needs to be properly 
+   * initialized and have a group called "HiOpState".
+   */
+  inline void load_state()
+  {
+    iter_chkpnt_.load(this);
+  }
+
+  /**
+   * This method loads the state of the algorithm from the file whose name is passed as a string
+   * argument. HiOp expected that the file contains a axom::sidre::DataStore that was previously saved 
+   * using one of the @save_state methods above.
+   * 
+   */
+  inline void load_state(const std::string& filename)
+  {
+    iter_chkpnt_.load(filename, this);
+  }
+
+
+  /// Setter for the primal steplength.
   inline void set_alpha_primal(const double alpha_primal) { _alpha_primal = alpha_primal; }
 
 protected:
@@ -245,6 +314,9 @@ class hiopAlgFilterIPMBase {
   hiopNlpFormulation* nlp;
   hiopFilter filter;
 
+  /// Helper for saving/loading algorithm state to disk. 
+  Checkpointing iter_chkpnt_;
+
   hiopLogBarProblem* logbar;
 
   /* Iterate, search directions (managed by this (algorithm) class) */