egs_run_control.h

Go to the documentation of this file.

/*
###############################################################################
#
#  EGSnrc egs++ run control headers
#  Copyright (C) 2015 National Research Council Canada
#
#  This file is part of EGSnrc.
#
#  EGSnrc is free software: you can redistribute it and/or modify it under
#  the terms of the GNU Affero General Public License as published by the
#  Free Software Foundation, either version 3 of the License, or (at your
#  option) any later version.
#
#  EGSnrc 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 Affero General Public License for
#  more details.
#
#  You should have received a copy of the GNU Affero General Public License
#  along with EGSnrc. If not, see <http://www.gnu.org/licenses/>.
#
###############################################################################
#
#  Author:          Iwan Kawrakow, 2005
#
#  Contributors:    Frederic Tessier
#                   Ernesto Mainegra-Hing
#                   Blake Walters
#                   Reid Townson
#
###############################################################################
*/
 
 
#ifndef EGS_RUN_CONTROL_
#define EGS_RUN_CONTROL_
 
#include "egs_libconfig.h"
#include "egs_timer.h"
#include "egs_input_struct.h"
 
#include <iostream>
using namespace std;
 
class EGS_Application;
class EGS_Input;
 
inline void addRunControlBlock(shared_ptr<EGS_InputStruct> blockPtr) {
    shared_ptr<EGS_BlockInput> runBlock = blockPtr->addBlockInput("run control");
    runBlock->addSingleInput("ncase", true, "The number of histories to simulate.");
    runBlock->addSingleInput("nbatch", false, "The number of batches to divide the simulation into. After each batch, a checkpoint is created to allow resuming the simulation. For simulations with very large intermediate data (like a high resolution dose grid), reducing nbatch to 1 can speed up the simulation. Defaults to 10.");
    runBlock->addSingleInput("nchunk", false, "For parallel runs, each job splits its portion of the simulation into nchunk serial chunks, and each of those chunks is divided into nbatch batches. After each chunk, the parallel job grabs a new portion of the simulation to work on. Defaults to 10.");
    runBlock->addSingleInput("max cpu hours allowed", false, "The number hours after which the simulation will be haulted. Defaults to -1, which is no limit.");
    runBlock->addSingleInput("statistical accuracy sought", false, "The statistical uncertainty for a particular quantity of interest, below which the simulation will be haulted. Note that the quantity must be defined by the application (e.g. the cavity dose in egs_chamber), and in general is undefined (e.g. this input does nothing for egs_app).");
    runBlock->addSingleInput("geometry error limit", false, "The number of geometry errors that will be allowed to occur, before haulting the simulation. Defaults to 0.");
    runBlock->addSingleInput("calculation", false, "The calculation type: first (default, runs a new simulation), resume (continue a crashed simulation), analyze (prints results), combine (combines results from a parallel run). Defaults to 'first'.", {"first", "resume", "analyze", "combine"});
}
 
inline string addRunControlExample() {
    string example = {
        R"(
:start run control:
    ncase                       = 1e4
    nbatch                      = 10    #[optional]
    nchunk                      = 10    #[optional]
    statistical accuracy sought = 5     #[optional]
    max cpu hours allowed       = 0.5   #[optional]
    calculation                 = first #[optional]
    geometry error limit        = 2     #[optional]
:stop run control:
)"};
    return example;
}
 
class EGS_EXPORT EGS_RunControl {
 
public:
 
    EGS_RunControl(EGS_Application *app);
 
    virtual ~EGS_RunControl();
 
    void setNcase(EGS_I64 n) {
        if (n > 0) {
            ncase = n;
        }
    };
 
    void setNbatch(int n) {
        if (n > 0) {
            nbatch = n;
        }
    };
 
    void setMaxTime(EGS_Float t) {
        maxt = t;
    };
 
    void setRequiredUncertainty(EGS_Float a) {
        accu = a;
    };
 
    EGS_I64 getNcase() const {
        return ncase;
    };
 
    int     getNbatch() const {
        return nbatch;
    };
 
    int     getNchunk() const {
        return nchunk;
    };
 
    virtual int     startSimulation();
 
    virtual EGS_I64 getNextChunk() {
        return getNcase() - ndone;
    };
 
    virtual int     finishSimulation();
 
    virtual bool    startBatch(int,EGS_I64);
 
    virtual bool    finishBatch();
 
    virtual void    describeRCO();
    virtual bool    storeState(ostream &data);
    virtual bool    setState(istream &data);
    virtual bool    addState(istream &data);
    virtual void    resetCounter();
    virtual bool    getCombinedResult(double &, double &) const {
        return false;
    };
 
    virtual EGS_I64 getNdone() const {
        return ndone;
    };
 
    virtual void    setNdone(EGS_I64 Ndone) {
        ndone = Ndone;
    };
 
    virtual void    incrementNdone() {
        ++ndone;
    };
 
    virtual EGS_Float getCPUTime() const {
        return cpu_time+previous_cpu_time;
    };
 
    enum RCOType {
        simple,   
        uniform,  
        balanced  
    };
 
    static EGS_RunControl *getRunControlObject(EGS_Application *);
 
    int             geomErrorCount, geomErrorMax;
 
protected:
 
    EGS_Application *app;
    EGS_Input       *input;
 
    EGS_I64         ncase;  // number of histories.
    EGS_I64         ndone;  // histories done so far.
    EGS_Float       maxt;   // maximum time to run in hours.
    EGS_Float       accu;   // statistical uncertainty sought.
    int             nbatch; // number of batches.
    int             resume;// =0 => fresh calculation
    // =1 => resume calculation
    // =2 => analyze results
    // =3 => combine parallel run
    int             nchunk; // number of simulation "chunks"
 
    RCOType         rco_type; 
 
    EGS_Timer       timer;
    EGS_Float       cpu_time;
    EGS_Float       previous_cpu_time;
 
};
 
class EGS_FileLocking;
 
class EGS_EXPORT EGS_JCFControl : public EGS_RunControl {
 
public:
 
    EGS_JCFControl(EGS_Application *, int Nbuf=1024);
    ~EGS_JCFControl();
    void setNchunkForParallel(int n) {
        if (n > 0) {
            nchunk = n;
        }
    };
    int  startSimulation();
    EGS_I64 getNextChunk();
    int  finishSimulation();
    bool getCombinedResult(double &, double &) const;
 
protected:
 
    EGS_I64 nleft, ntot;
    double  tsum, tsum2, tcount, norm;
    double  last_sum, last_sum2, last_count;
    unsigned long start_time;
    int    njob;
    int    npar;
    int    ipar;
    int    ifirst;
    bool   first_time;
    bool   removed_jcf;
    int    nbuf;
    char   *buf;
 
    EGS_FileLocking *p;
 
    bool   createControlFile();
    bool   openControlFile();
    bool   closeControlFile();
    bool   lockControlFile();
    bool   unlockControlFile();
    bool   rewindControlFile();
    bool   readControlFile();
    bool   writeControlFile();
    virtual bool writeControlString();
    virtual bool readControlString();
 
};
 
class EGS_EXPORT EGS_UniformRunControl : public EGS_RunControl {
 
public:
 
    EGS_UniformRunControl(EGS_Application *app);
    ~EGS_UniformRunControl() {};
 
    void  describeRCO();
 
    int  startSimulation();
 
    int  finishSimulation();
 
protected:
 
    int milliseconds;   // time interval for checking
    // if all jobs finished (default 1000 ms)
 
    int check_intervals;// Number of intervals to check
    // if all jobs done (default 5)
 
    int    njob;
    int    npar;
    int    ipar;
    int    ifirst;
    bool   check_egsdat;// If true, and a 'watcher' job, produce intermediate results
    bool   watcher_job; // If true, job is a 'watcher'
};
 
#endif