vOptimizer.hh

Go to the documentation of this file.

/*
This file is part of CASToR.

    CASToR is free software: you can redistribute it and/or modify it under the
    terms of the GNU General Public License as published by the Free Software
    Foundation, either version 3 of the License, or (at your option) any later
    version.

    CASToR is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
    details.

    You should have received a copy of the GNU General Public License along with
    CASToR (in file GNU_GPL.TXT). If not, see <http://www.gnu.org/licenses/>.

Copyright 2017-2018 all CASToR contributors listed below:

    --> current contributors: Thibaut MERLIN, Simon STUTE, Didier BENOIT, Claude COMTAT, Marina FILIPOVIC, Mael MILLARDET
    --> past contributors: Valentin VIELZEUF

This is CASToR version 2.0.
*/

#ifndef VOPTIMIZER_HH
#define VOPTIMIZER_HH 1

#include "gVariables.hh"
#include "oImageDimensionsAndQuantification.hh"
#include "oImageSpace.hh"
#include "vDataFile.hh"
#include "oProjectionLine.hh"

class vOptimizer
{
  // -------------------------------------------------------------------
  // Constructor & Destructor
  public:
    vOptimizer();
    virtual ~vOptimizer();


  // -------------------------------------------------------------------
  // Public member functions
  public:
    void ShowHelp();
    int CheckParameters();
    int Initialize();
    int UpdateVisitedVoxels();
    int PreDataUpdateStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);
    int PostDataUpdateStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);


  // -------------------------------------------------------------------
  // Virtual public member functions that may be overloaded by specific child optimizers
  public:
    virtual int DataStep1ForwardProjectModel( oProjectionLine* ap_Line, vEvent* ap_Event,
                                              int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
                                              int a_thread );
    virtual int DataStep2Optional( oProjectionLine* ap_Line, vEvent* ap_Event,
                                   int a_bed, int a_timeFrame, int a_respGate, int a_cardGate, int a_iteration,
                                   int a_thread );
    virtual int DataStep3BackwardProjectSensitivity( oProjectionLine* ap_Line, vEvent* ap_Event,
                                                     int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
                                                     int a_thread );
    virtual int DataStep4Optional( oProjectionLine* ap_Line, vEvent* ap_Event,
                                   int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
                                   int a_iteration, int a_thread );
    virtual int DataStep5ComputeCorrections( oProjectionLine* ap_Line, vEvent* ap_Event,
                                             int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
                                             int a_thread );
    virtual int DataStep6Optional( oProjectionLine* ap_Line, vEvent* ap_Event,
                                   int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
                                   int a_iteration, int a_thread );
    virtual int DataStep7BackwardProjectCorrections( oProjectionLine* ap_Line, vEvent* ap_Event,
                                                     int a_bed, int a_timeFrame, int a_respGate, int a_cardGate,
                                                     int a_thread );
    virtual int DataStep8ComputeFOM( oProjectionLine* ap_Line, vEvent* ap_Event,
                                     int a_timeFrame, int a_respGate, int a_cardGate,
                                     int a_thread );
    virtual int ImageUpdateStep( int a_iteration, int a_nbSubsets );


  // -----------------------------------------------------------------------------------------
  // Virtual private member functions that may be overloaded by specific child optimizers
  private:
    virtual int PreDataUpdateSpecificStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);
    virtual int PostDataUpdateSpecificStep(int a_iteration, int a_nbIterations, int a_subset, int* ap_nbSubsets);

  // -----------------------------------------------------------------------------------------
  // Pure virtual public member functions that need to be implemented by child optimizers
  public:
    virtual int ReadConfigurationFile( const string& a_configurationFile ) = 0;
    virtual int ReadOptionsList( const string& a_optionsList ) = 0;


  // -----------------------------------------------------------------------------------------
  // Pure virtual private member functions that need to be implemented by child optimizers
  private:
    virtual void ShowHelpSpecific() = 0;
    virtual int CheckSpecificParameters() = 0;
    virtual int InitializeSpecific() = 0;
    virtual int SensitivitySpecificOperations( FLTNB a_data, FLTNB a_forwardModel, FLTNB* ap_weight,
                                               FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_blankValue,
                                               FLTNB a_quantificationFactor, oProjectionLine* ap_Line ) = 0;
    virtual int DataSpaceSpecificOperations( FLTNB a_data, FLTNB a_forwardModel, FLTNB* ap_backwardValues,
                                             FLTNB a_multiplicativeCorrections, FLTNB a_additiveCorrections, FLTNB a_blankValue,
                                             FLTNB a_quantificationFactor, oProjectionLine* ap_Line ) = 0;
    virtual int ImageSpaceSpecificOperations( FLTNB a_currentImageValue, FLTNB* ap_newImageValue,
                                              FLTNB a_sensitivity, FLTNB* ap_correctionValues, INTNB a_voxel ) = 0;


  // -------------------------------------------------------------------
  // Public Get & Set functions
  public:
    inline void SetVerbose(int a_verbose)
           {m_verbose = a_verbose;}
    inline void SetImageDimensionsAndQuantification(oImageDimensionsAndQuantification* ap_ImageDimensionsAndQuantification)
           {mp_ImageDimensionsAndQuantification = ap_ImageDimensionsAndQuantification;}
    inline void SetImageSpace(oImageSpace* ap_ImageSpace)
           {mp_ImageSpace = ap_ImageSpace;}
    inline void SetNbTOFBins(int a_nbTOFBins)
           {m_nbTOFBins = a_nbTOFBins;}
    inline void SetDataMode(int a_dataMode)
           {m_dataMode = a_dataMode;}
    inline void SetDataType(int a_dataType)
           {m_dataType = a_dataType;}
    inline void SetDataSpec(int a_dataSpec)
           {m_dataSpec = a_dataSpec;}
    inline void SetAttenuationImage(FLTNB* ap_attenuationImage, int a_thread)
           {m2p_attenuationImage[a_thread] = ap_attenuationImage;}
    inline void SetFOMFlag(bool a_optimizerFOMFlag)
           {m_optimizerFOMFlag = a_optimizerFOMFlag;}
    inline void SetImageStatFlag(bool a_optimizerImageStatFlag)
           {m_optimizerImageStatFlag = a_optimizerImageStatFlag;}
    inline int GetNbBackwardImages()
           {return m_nbBackwardImages;}
    inline FLTNB GetInitialValue()
           {return m_initialValue;}
    /*
    inline bool GetAcceptPenalty()
           {return m_penaltyEnergyFunctionDerivativesOrder>0;}
    inline int GetPenaltyEnergyFunctionDerivativesOrder()
           {return m_penaltyEnergyFunctionDerivativesOrder;}
    */


  // -------------------------------------------------------------------
  // Private member functions
  protected:
    FLTNB ComputeSensitivity( FLTNB**** a4p_sensitivityImage,
                              int a_timeBasisFunction, int a_respBasisFunction, int a_cardBasisFunction,
                              int a_voxel, int a_nbSubsets );
    FLTNB ForwardProject( oProjectionLine* ap_Line, FLTNB* ap_image = NULL );
    void BackwardProject( oProjectionLine* ap_Line, FLTNB* ap_image, FLTNB a_value );

  // -------------------------------------------------------------------
  // Data members
  protected:
    int m_verbose;                         
    int m_nbBackwardImages;                
    int m_nbTOFBins;                       
    FLTNB** m2p_forwardValues;             
    FLTNB*** m3p_backwardValues;           
    FLTNB m_initialValue;                  
    bool m_listmodeCompatibility;          
    bool m_histogramCompatibility;         
    bool m_emissionCompatibility;          
    bool m_transmissionCompatibility;      
    oImageDimensionsAndQuantification* 
      mp_ImageDimensionsAndQuantification; 
    oImageSpace* mp_ImageSpace;             
    int m_dataMode;                        
    int m_dataType;                        
    int m_dataSpec;                        
    FLTNB** m2p_attenuationImage;          
    // Optimizer figures-of-merit computation
    bool m_optimizerFOMFlag;               
    FLTNB**** m4p_FOMLogLikelihood;        
    FLTNB**** m4p_FOMRMSE;                 
    uint64_t**** m4p_FOMNbBins;            
    HPFLTNB**** m4p_FOMNbData;              
    // Image update statistics
    bool m_optimizerImageStatFlag;         
    INTNB* mp_imageStatNbVox;              
    FLTNB* mp_imageStatMin;                
    FLTNB* mp_imageStatMax;                
    HPFLTNB* mp_imageStatMean;              
    HPFLTNB* mp_imageStatVariance;          
    HPFLTNB* mp_correctionStatMean;         
    HPFLTNB* mp_correctionStatVariance;     
    //int m_penaltyEnergyFunctionDerivativesOrder; /*!< The penalty derivatives order accepted by the specific optimizer (0 if none) */
};


// ----------------------------------------------------------------------
// Part of code that manages the auto declaration of children classes
// ----------------------------------------------------------------------

// Macro for the function that creates the object
#define FUNCTION_OPTIMIZER(CLASS) \
  static vOptimizer *make_optimizer() { return new CLASS(); };

// Macro for the class that links the appropriate function to the map of objects
#define CLASS_OPTIMIZER(NAME,CLASS)                                                           \
  class NAME##OptimizerCreator                                                                \
  {                                                                                           \
    public:                                                                                   \
      NAME##OptimizerCreator()                                                                \
        { sAddonManager::GetInstance()->mp_listOfOptimizers[#NAME] = CLASS::make_optimizer; } \
  };                                                                                          \
  static NAME##OptimizerCreator OptimizerCreator##NAME;

#endif