Geant4 LXR

Cross-Referencing   Geant4
Geant4/processes/biasing/management/include/G4VBiasingOperator.hh

   //
   // ********************************************************************
   // * License and Disclaimer                                           *
   // *                                                                  *
   // * The  Geant4 software  is  copyright of the Copyright Holders  of *
   // * the Geant4 Collaboration.  It is provided  under  the terms  and *
   // * conditions of the Geant4 Software License,  included in the file *
   // * LICENSE and available at  http://cern.ch/geant4/license .  These *
   // * include a list of copyright holders.                             *
  // *                                                                  *
  // * Neither the authors of this software system, nor their employing *
  // * institutes,nor the agencies providing financial support for this *
  // * work  make  any representation or  warranty, express or implied, *
  // * regarding  this  software system or assume any liability for its *
  // * use.  Please see the license in the file  LICENSE  and URL above *
  // * for the full disclaimer and the limitation of liability.         *
  // *                                                                  *
  // * This  code  implementation is the result of  the  scientific and *
  // * technical work of the GEANT4 collaboration.                      *
  // * By using,  copying,  modifying or  distributing the software (or *
  // * any work based  on the software)  you  agree  to acknowledge its *
  // * use  in  resulting  scientific  publications,  and indicate your *
  // * acceptance of all terms of the Geant4 Software license.          *
  // ********************************************************************
  //
  // G4VBiasingOperator, G4BiasingOperatorStateNotifier
  //
  // Class Description:
  //
  // An abstract class to pilot the biasing in a logical volume. This
  // class is for *making decisions* on biasing operations to be applied.
  // These ones are represented by the G4VBiasingOperation class.
  // The volume in which biasing is applied is specified by the
  // AttachTo(const G4LogicalVolume *) method. This has to be specified
  // at detector construction time in the method ConstructSDandField() of
  // G4VUsedDetectorConstruction.
  //
  // At tracking time the biasing operator is messaged by each
  // G4BiasingProcessInterface object attached to the current track. For
  // example, if three physics processes are under biasing, and if an
  // additional G4BiasingProcessInterface is present to handle non-physics
  // based biasing (splitting, killing), the operator will be messaged by
  // these four G4BiasingProcessInterface objects.
  // The idendity of the calling G4BiasingProcessInterface is known
  // to the G4VBiasingOperator by passing this process pointer to the
  // operator.
  //
  // ** Mandatory methods: **
  //
  // Three types of biasing are to be decided by the G4VBiasingOperator:
  //
  //   1) non-physics-based biasing:
  //   -----------------------------
  //   Meant for pure killing/splitting/etc. biasing operations, not 
  //   associated to a physics process:
  //
  //   virtual G4VBiasingOperation* ProposeNonPhysicsBiasingOperation( const G4Track* track,
  //                                                                   const G4BiasingProcessInterface* callingProcess ) = 0;
  //
  //   Arguments are the current track, and the G4BiasingProcessInterface
  //   pointer making the call to the operator. In this case, this process
  //   does not wrap a physics process and 
  //                callingProcess->GetWrappedProcess() == 0.
  //
  //   The G4VBiasingOperation pointer returned is the operation to be
  //   applied. Zero can be returned. This operation will limit the
  //   step and propose a final state.
  //   
  //   This method is the first operator method called, it is called at the
  //   by the PostStepGetPhysicalInterationLength(...) method of the
  //   G4BiasingProcessInterface.
  //
  //   2) physics-based biasing:
  //   -------------------------
  //   Physics-based biasing operations are of two types:
  //     - biasing of the physics process occurrence interaction law
  //     - biasing of the physics process final state production
  //
  //   a) The biasing of the occurrence interaction law is proposed by:
  //
  //   virtual G4VBiasingOperation*  ProposeOccurenceBiasingOperation( const G4Track* track, 
  //                                                                   const G4BiasingProcessInterface* callingProcess ) = 0;
  //   The current G4Track pointer and the G4BiasingProcessInterface
  //   pointer of the process calling the operator are passed. The
  //   G4BiasingProcessInterface process wraps an actual physics process
  //   which pointer can be obtained with
  //                callingProcess->GetWrappedProcess() .
  //
  //   The biasing operation returned will be asked for its biasing
  //   interaction by the calling process, which will be a const object
  //   for the process. All setup and sampling regarding this law should be done
  //   in the operator before returning the related operation to the process.
  //
  //   This method is the second operator one called in a step, it is called by
  //   the PostStepGetPhysicalInterationLength(...) method of the
  //   G4BiasingProcessInterface.
  //
  //   b) The biasing of the physics process final state is proposed by:
  //
 //   virtual G4VBiasingOperation* ProposeFinalStateBiasingOperation( const G4Track* track,
 //                                                                   const G4BiasingProcessInterface* callingProcess ) = 0;
 //
 //   The operator can propose a biasing operation that will handle the
 //   physic process final state biasing. As in previous case a) the
 //   G4BiasingProcessInterface process wraps an actual physics process
 //   which pointer can be obtained with:
 //                callingProcess->GetWrappedProcess() .
 //
 //   Cases a) and b) are handled independently, and one or two of these
 //   biasing types can be provided in the same step.
 //
 //   This method is the last operator one called in a step, it is called
 //   by the PostStepDoIt(...) method of the G4BiasingProcessInterface.
 //
 //
 // ** Optional methods: **
 //
 //     At the end of the step, the operator is messaged by the G4BiasingProcessInterface
 // for operation(s) which have been applied during the step. One of the two following
 // methods is called:
 //
 // virtual void OperationApplied( const G4BiasingProcessInterface* callingProcess,
 //                                G4BiasingAppliedCase biasingCase,
 //          G4VBiasingOperation* operationApplied,
 //                                const G4VParticleChange* particleChangeProduced );
 // At most a single biasing operation was applied by the process:
 //    - a non-physics biasing operation was applied, biasingCase == BAC_NonPhysics ;
 //    - physics-based biasing:
 //      - the operator requested no biasing operations, and did let the physics
 //        process go : biasingCase ==  BAC_None;
 //      - a single final state biasing was proposed, with no concomittant occurrence:
 //        biasingCase ==  BAC_FinalState;
 // The operation applied and final state passed to the tracking (particleChangeProduced) are
 // passed as information to the operator.
 // 
 // virtual void OperationApplied( const G4BiasingProcessInterface* callingProcess,
 //                                G4BiasingAppliedCase biasingCase,
 //          G4VBiasingOperation* occurenceOperationApplied,
 //                                G4double weightForOccurenceInteraction,
 //          G4VBiasingOperation* finalStateOperationApplied,
 //                                const G4VParticleChange* particleChangeProduced );
 // This method is called in case an occurrence biasing operation has been applied during the step.
 // The biasingCase value is then the one of the final state biasing, if any : depending on if the
 // occurrence operation was applied alone and together with a final state operation, the
 // biasingCase will take values:
 //     - occurrence biasing alone : biasingCase == BAC_None ;
 //       in which case finalStateOperationApplied == 0;
 //     - occurrence biasing + final state biasing : biasingCase ==  BAC_FinalState;
 // The particleChangeProduced is the one *before* application of the weight for occurrence : hence
 // either the particle change of the (analog) physics process, or the biased final state, resulting
 // from the biasing by the finalStateOperationApplied operation.
 //
 // Author: M.Verderi (LLR), November 2013
 // --------------------------------------------------------------------
 #ifndef G4VBiasingOperator_hh
 #define G4VBiasingOperator_hh 1
 
 #include "globals.hh"
 #include "G4BiasingAppliedCase.hh"
 #include "G4Cache.hh"
 #include "G4VStateDependent.hh"
 
 #include <map>
 #include <vector>
 
 class G4VBiasingOperation;
 class G4Track;
 class G4BiasingProcessInterface;
 class G4LogicalVolume;
 class G4VParticleChange;
 class G4BiasingOperatorStateNotifier;
 
 class G4VBiasingOperator
 {
   // -- State machine used to inform operators
   // -- about run starting.
   // -- Defined at the end of this file.
   friend class G4BiasingOperatorStateNotifier;
   
   public:
 
     // ---------------
     // -- Constructor:
     // ---------------
     G4VBiasingOperator(const G4String& name);
     virtual ~G4VBiasingOperator() = default;
   
     // ---- Configure() is called in sequential mode or for master thread in MT mode.
     // ---- It is in particular aimed at registering ID's to physics model at run initialization.
     virtual void Configure() {}
     // ---- ConfigureForWorker() is called in MT mode only, and only for worker threads.
     // ---- It is not not to be used to register ID's to physics model catalog.
     virtual void ConfigureForWorker() {}
     // ---- inform the operator of the start of the run:
     virtual void StartRun() {}
     // ---- inform the operator of the start (end) of the tracking of a new track:
     virtual void StartTracking( const G4Track* /* track */ ) {}
     virtual void EndTracking() {}
 
     // --------------------
     // -- public interface:
     // --------------------
     // -- needed by user:
     const G4String& GetName() const { return fName; }
     void AttachTo( const G4LogicalVolume* ); // -- attach to single volume 
 
     G4BiasingAppliedCase GetPreviousBiasingAppliedCase() const
       { return fPreviousBiasingAppliedCase; }
     // -- all operators (might got to a manager):
     static const std::vector < G4VBiasingOperator* >& GetBiasingOperators();
       // -- get operator associated to a logical volume:
     static G4VBiasingOperator* GetBiasingOperator( const G4LogicalVolume* );
       // -- might go to a manager ; or moved to volume
 
     // -- used by biasing process interface, or used by another operator (not expected to be invoked differently than with these two cases):
     G4VBiasingOperation* GetProposedOccurenceBiasingOperation( const G4Track* track,
                          const G4BiasingProcessInterface* callingProcess );
     G4VBiasingOperation* GetProposedFinalStateBiasingOperation( const G4Track* track,
                          const G4BiasingProcessInterface* callingProcess );
     G4VBiasingOperation* GetProposedNonPhysicsBiasingOperation( const G4Track* track,
                          const G4BiasingProcessInterface* callingProcess );
     void ExitingBiasing( const G4Track* track,
                          const G4BiasingProcessInterface* callingProcess );
 
     void ReportOperationApplied( const G4BiasingProcessInterface* callingProcess,
                          G4BiasingAppliedCase biasingCase,
                          G4VBiasingOperation* operationApplied,
                          const G4VParticleChange* particleChangeProduced );
     void ReportOperationApplied( const G4BiasingProcessInterface* callingProcess,
                          G4BiasingAppliedCase biasingCase,
                          G4VBiasingOperation* occurenceOperationApplied,
                          G4double weightForOccurenceInteraction,
                          G4VBiasingOperation* finalStateOperationApplied,
                          const G4VParticleChange* particleChangeProduced );
   
     const G4VBiasingOperation* GetPreviousNonPhysicsAppliedOperation()
       { return  fPreviousAppliedNonPhysicsBiasingOperation; }
 
   protected:
 
     // -- mandatory methods to let the operator tell about biasing operations to be applied:
     // -------------------------------------------------------------------------------------
     // -- These three methods have the same arguments passed : the current G4Track pointer, and the pointer of the
     // -- G4BiasingProcessInterface instance calling this biasing operator. This same biasing operator will be called by each
     // -- of the G4BiasingProcessInterface instances, meaning for example that:
     // --     - if one G4BiasingProcessInterface with no wrapped physics process exits, ProposeNonPhysicsBiasingOperation(...)
     // --       will be called one time at the beginning of the step,
     // --     - if three G4BiasingProcessInterface instances exist, each of these one wrapping a physics process (eg
     // --       conversion, Compton, photo-electric), ProposeOccurenceBiasingOperation(...) will be called three times,
     // --       by each of these instances, at the beginning of the step and ProposeFinalStateBiasingOperation(...) will
     // --       also be called by each of these instances, at the PostStepDoIt level.
     // -- If a null pointer is returned, the analog -unbiased- behavior is adopted.
     // -- non-physics-based biasing:
     // -----------------------------
     // -- [ First operator method called, at the PostStepGetPhysicalInterationLength(...) level. ]
     virtual G4VBiasingOperation* ProposeNonPhysicsBiasingOperation( const G4Track* track, const G4BiasingProcessInterface* callingProcess ) = 0;
 
     // -- physics-based biasing:
     // -------------------------
     // -- Method to propose an occurrence biasing operation : ie a change of the interaction length distribution. The proposed
     // -- biasing operation will then be asked for its interaction law.
     // -- Note that *** all sanity checks regarding the operation and its interaction law will have to have been performed
     // -- before returning the biasing operation pointer *** as no corrective/aborting actions will be possible beyond this point.
     // -- The informations provided by the G4BiasingProcessInterface calling process (previous occurrence operation, previous step length,
     // -- etc.) might be useful for doing this. They will be useful also to decide with continuing with a same operation proposed
     // -- in the previous step, updating the interaction law taking into account the new G4Track state and the previous step size.
     // -- [ Second operator method called, at the PostStepGetPhysicalInterationLength(...) level. ]
     virtual G4VBiasingOperation* ProposeOccurenceBiasingOperation( const G4Track* track, const G4BiasingProcessInterface* callingProcess ) = 0;
 
     // -- [ Third operator method called, at the PostStepDoIt(...) level. ]
     virtual G4VBiasingOperation* ProposeFinalStateBiasingOperation( const G4Track* track, const G4BiasingProcessInterface* callingProcess ) = 0;
 
     // -- optional methods for further information passed to the operator:
     // -------------------------------------------------------------------
     // ---- report to operator about the operation applied, the biasingCase value provides the case of biasing applied:
     virtual void OperationApplied( const G4BiasingProcessInterface* callingProcess, G4BiasingAppliedCase biasingCase,
            G4VBiasingOperation* operationApplied, const G4VParticleChange* particleChangeProduced );
     // ---- same as above, report about the operation applied, for the case an occurrence biasing was applied, together or not with a final state biasing.
     // ---- The variable biasingCase tells if the final state is a biased one or not. **But in all cases**, this call happens only
     // ---- for an occurrence biasing : ie the occurrence weight is applied on top of the particleChangeProduced, which is the particle
     // ---- *before* the weight application for occurence biasing.
     virtual void OperationApplied( const G4BiasingProcessInterface* callingProcess, G4BiasingAppliedCase biasingCase,
            G4VBiasingOperation* occurenceOperationApplied, G4double weightForOccurenceInteraction,
            G4VBiasingOperation* finalStateOperationApplied, const G4VParticleChange* particleChangeProduced );
 
     // ---- method to inform operator that its biasing control is over (exit volume, or end of tracking):
     // ---- [Called at the beginning of next step, or at the end of tracking.]
     virtual void ExitBiasing( const G4Track* track, const G4BiasingProcessInterface* callingProcess );
 
     // ----------------------------------
     // -- Delegation to another operator:
     // ----------------------------------
     // -- An operator may wish to select a sequence of operations already implemented in an
     // -- existing biasing operator. In this case, this operator can delegate its work to
     // -- the "delegated" one by calling DelegateTo( G4VBiasingOperation* delegated );
     // -- Should we have:
     // --    - a "step delegation" -where the delegation is made for the current step only-
     // --    - a long delegation where the delegation can hold over several steps, as long as
     // --      the scheme is not completed. [let's call it "scheme delegation"]
     // --      In this case the "execution/delegated" operator might switch off back the
     // --      delegation from the "delegator" when it knows it has done its work.
     // -- Add a private SetDelegator( G4VBiasingOperator* ) method, call on the delegated
     // -- operator.
     // -- For a step long delegation, the ReportOperationApplied should be used to "unset"
     // -- the delegation. For a scheme long delegation, the delegater operator will unset
     // -- itself has delegation. Likely to happen in the ReportOperationApplied as well,
     // -- but not sure it is mandatory though.
   
   private:
 
     const G4String fName;
     // -- thread local:
     static G4MapCache< const G4LogicalVolume*, G4VBiasingOperator* > fLogicalToSetupMap;
     // -- thread local:
     static G4VectorCache<G4VBiasingOperator* > fOperators;
 
     // -- thread local:
     static G4Cache< G4BiasingOperatorStateNotifier* > fStateNotifier;
 
     // -- For this operator:
     std::vector< const G4LogicalVolume* > fRootVolumes;
     std::map< const G4LogicalVolume*, G4int > fDepthInTree;
   
     // -- current operation:
     G4VBiasingOperation* fOccurenceBiasingOperation = nullptr;
     G4VBiasingOperation* fFinalStateBiasingOperation = nullptr;
     G4VBiasingOperation* fNonPhysicsBiasingOperation = nullptr;
   
     // -- previous operations:
     const G4VBiasingOperation* fPreviousProposedOccurenceBiasingOperation = nullptr;
     const G4VBiasingOperation* fPreviousProposedFinalStateBiasingOperation = nullptr;
     const G4VBiasingOperation* fPreviousProposedNonPhysicsBiasingOperation = nullptr;
     const G4VBiasingOperation* fPreviousAppliedOccurenceBiasingOperation = nullptr;
     const G4VBiasingOperation* fPreviousAppliedFinalStateBiasingOperation = nullptr;
     const G4VBiasingOperation* fPreviousAppliedNonPhysicsBiasingOperation = nullptr;
     G4BiasingAppliedCase fPreviousBiasingAppliedCase = BAC_None;
 };
 
 // -- state machine to get biasing operators
 // -- messaged at the beginning of runs:
 
 class G4BiasingOperatorStateNotifier : public G4VStateDependent
 {
   public:
 
     G4BiasingOperatorStateNotifier();
     ~G4BiasingOperatorStateNotifier() = default;
 
     G4bool Notify(G4ApplicationState requestedState);
 
   private:
 
     G4ApplicationState fPreviousState;
 };
 
 #endif