This file defines the C/C++ interface to the EGSnrc mortran back-end. More...

#include "egs_config1.h"
#include "array_sizes.h"

Classes
struct	EGS_Stack
	A structure corresponding to the EGSnrc particle stack common block `STACK`. More...

struct	EGS_Bounds
	A structure corresponding to the EGSnrc transport threshold energies common block `BOUNDS`. More...

struct	EGS_Thresh
	A structure corresponding to the particle production threshold energies common block `THRESH`. More...

struct	EGS_Epcont
	A structure corresponding to the `EPCONT` common block. More...

struct	EGS_EtControl
	A structure corresponding to the `ET_control` common block. More...

struct	EGS_Media
	A structure corresponding to the `MEDIA` common block. More...

struct	EGS_Rayleigh
	A structure corresponding to the `rayleigh_inputs` common block. More...

struct	EGS_Useful
	A structure corresponding to the `USEFUL` common block. More...

struct	EGS_XOptions
	A structure corresponding to the `xsection_options` common block. More...

struct	EGS_VarianceReduction
	A structure corresponding to the `egs_vr` common block. More...

struct	EGS_IO
	A structure corresponding to the `egs_io` common block. More...

struct	EGS_emfInputs
	A structure corresponding to the `EMF_INPUTS` common block. More...

Macros
#define	MXAUS 35 /* there are 35 different calls to ausgab */

#define	egsFinish F77_OBJ_(egs_finish,EGS_FINISH)

#define	egsAddMedium F77_OBJ_(egs_add_medium,EGS_ADD_MEDIUM)

#define	egsHatch F77_OBJ_(egs_hatch,EGS_HATCH)

#define	egsShower F77_OBJ_(egs_shower,EGS_SHOWER)

#define	egsRandomDefaultInit F77_OBJ_(egs_init_default_rng,EGS_INIT_DEFAULT_RNG)

#define	egsRandomInit F77_OBJ_(egs_init_rng,EGS_INIT_RNG)

#define	egsRandomGet F77_OBJ_(egs_get_rndm,EGS_GET_RNDM)

#define	egsFillRandomArray F77_OBJ_(egs_fill_rndm_array,EGS_GET_RNDM_ARRAY)

#define	egsElapsedTime F77_OBJ_(egs_tot_time,EGS_TOT_TIME)

#define	egsCpuTime F77_OBJ_(egs_etime,EGS_ETIME)

#define	egsGetTransportParameter F77_OBJ_(get_transport_parameter,GET_TRANSPORT_PARAMETER)

#define	egsHowfar F77_OBJ_(egs_howfar,EGS_HOWFAR)

#define	egsHownear F77_OBJ_(egs_hownear,EGS_HOWNEAR)

#define	egsAusgab F77_OBJ_(egs_ausgab,EGS_AUSGAB)

#define	egsStartParticle F77_OBJ_(egs_start_particle,EGS_START_PARTICLE)

Functions
__extc__ void	egsInit (int argc, char **argv)
	Initializes the EGSnrc mortran back-end. More...

__extc__ void	egsFinish (void)
	Finish a simulation. More...

__extc__ EGS_I32	egsAddMedium (const char *medname, EGS_I32 length)
	Add a medium to the list of media. More...

__extc__ void	egsHatch (void)
	Initialize cross section data from a PEGS4 data file. More...

__extc__ void	egsShower (void)
	Transport the particles currently on the particle stack. More...

__extc__ void	egsRandomDefaultInit ()
	Initialize the EGSnrc RNG using default values. More...

__extc__ void	egsRandomInit (const EGS_I32 s1, const EGS_I32 s2)
	Initialize the EGSnrc RNG. More...

__extc__ void	egsRandomGet (EGS_Float *ranno)
	Get a single random number stored at the location pointed to by ranno. More...

__extc__ void	egsFillRandomArray (const EGS_I32 n, EGS_Float rarray)
	Get n random numbers stored in the array pointed to by rarray. More...

__extc__ EGS_Float	egsElapsedTime (int *flag)
	Get elapsed time. More...

__extc__ EGS_Float	egsCpuTime (void)
	Get the CPU time used since the process started. More...

__extc__ void	egsGetTransportParameter (const int *ounit)
	Get the transport parameter settings from the input file. More...

__extc__ void	egsHowfar (void)
	Calculate distance to the next boundary along the current direction of motion. More...

__extc__ void	egsHownear (EGS_Float *tperp)
	Calculate minimum perpendicular distance to any surrounding boundary and return it in tperp. More...

__extc__ void	egsAusgab (EGS_I32 *iarg)
	User scoring function. More...

__extc__ void	egsStartParticle (void)
	Start the transport of a new particle. More...

Variables
__extc__ struct EGS_Stack *	the_stack
	The address of the mortran `STACK` common block as a pointer to a C-structure of type EGS_Stack.

__extc__ struct EGS_Bounds *	the_bounds
	The address of the morrtan `BOUNDS` common block as a pointer to a C-structure of type EGS_Bounds.

__extc__ struct EGS_Thresh *	the_thresh
	The address of the mortran `THRESH` common block as a pointer to a C-structure of type EGS_Thresh.

__extc__ struct EGS_Epcont *	the_epcont
	The address of the mortran `EPCONT` common block as a pointer to a C-structure of type EGS_Epcont.

__extc__ struct EGS_EtControl *	the_etcontrol
	The address of the mortran `Et_Control` common block as a pointer to a C-structure of type EGS_EtControl.

__extc__ struct EGS_Media *	the_media
	The address of the mortran `MEDIA` common block as a pointer to a C-structure of type EGS_Media.

__extc__ struct EGS_Useful *	the_useful
	The address of the mortran `USEFUL` common block as a pointer to a C-structure of type EGS_Useful.

__extc__ struct EGS_XOptions *	the_xoptions
	The address of the mortran cross section options common block as a pointer to a C-structure of type EGS_XOptions.

__extc__ struct EGS_IO *	the_egsio
	The address of the mortran `egs_io` common block as a pointer to a C-structure of type EGS_IO.

__extc__ struct EGS_VarianceReduction *	the_egsvr
	The address of the mortran `egs_vr` common block as a pointer to a C-structure of type EGS_VarianceReduction.

__extc__ struct EGS_Rayleigh *	the_rayleigh
	The address of the mortran rayleigh_inputs common block as a pointer to a C-structure of type EGS_Rayleigh.

__extc__ struct EGS_emfInputs *	the_emf
	The address of the mortran EMF-INPUTS common block as a pointer to a C-structure of type EGS_emfInputs.

Detailed Description

This file defines the C/C++ interface to the EGSnrc mortran back-end.

Author: Iwan Kawrakow, NRC

C/C++-structures are defined for the most commonly used mortran common blocks such as the particle stack , the transport threshold energies, etc. The general naming convention is that for a common block XXX the C-structure will be called EGS_Xxx. For a detailed description of EGSnrc common blocks see PIRS-701. Note, however, that various common blocks are replaced in egs_c_interface2.macros to remove all dependences on the geometry and to combine various transport parameter otpions into a single common block so that fewer common blocks need to be "exported".

Not all common are "exported". If a definition of a C-structure for a given common block that you need to access in your user code is missing, simply follow the way this file defines the structures and define it in your user code. In principle the mortran common blocks can be accessed directly from C/C++. However, due to name mangling of Fortran symbols undertaken by the Fortran compiler, a common block named xxx may result in a symbol called xxx, xxx_, xxx__, XXX, XXX_ or XXX__, depending on the name mangling scheme used by the Fortran compiler. This is handled by the macros F77_OBJ(name,NAME) and F77_OBJ_(name,NAME) defined in egs_config1.h, which is created during the installation of the EGSnrc system. With these macros one could access e.g. the particle energies using

F77_OBJ(stack,STACK).E

Because the above is quite tedious, this file also defines the addresses of the mortran common blocks as pointers to the corresponding C-structures with the general naming convention that the_xxx points to the common block XXX, e.g. the_stack points to the STACK common block, the_bounds to the BOUNDS common block, etc.

This file also provides declarations of various EGSnrc mortran functions and subroutines and corresponding pre-processor macros for easier access (the name mangling also applies to function names and therefore to call the EGSnrc subroutine shower(), one must use F77_OBJ(shower,SHOWER)() ). Most of these functions are only relevant for developing EGSnrc applications in C. For EGSnrc C++ applications it is much easier to derive from the EGS_SimpleApplication or EGS_AdvancedApplication classes, which make the direct access to most of these functions unnecessary.

Definition in file egs_interface2.h.

Macro Definition Documentation

#define MXAUS 35 /* there are 35 different calls to ausgab */

Number of possible calls to the egsAusgab() or ausgab() functions

Definition at line 98 of file egs_interface2.h.

#define egsFinish F77_OBJ_(egs_finish,EGS_FINISH)

Shorthand notation for the egs_finish mortran subroutine

Definition at line 714 of file egs_interface2.h.

#define egsAddMedium F77_OBJ_(egs_add_medium,EGS_ADD_MEDIUM)

Shorthand notation for the egs_add_medium mortran function

Definition at line 727 of file egs_interface2.h.

#define egsHatch F77_OBJ_(egs_hatch,EGS_HATCH)

Shorthand notation for the HATCH subroutine (which is renamed to egs_hatch for the C/C++ interface using mortran's replacemant capabilities)

Definition at line 744 of file egs_interface2.h.

#define egsShower F77_OBJ_(egs_shower,EGS_SHOWER)

Shorthand notation for the SHOWER subroutine (which is renamed to egs_shower for the C/C++ interface using mortran's replacemant capabilities)

Definition at line 760 of file egs_interface2.h.

#define egsRandomDefaultInit F77_OBJ_(egs_init_default_rng,EGS_INIT_DEFAULT_RNG)

Shorthand notation for the egs_init_default_rng mortran subroutine

Definition at line 778 of file egs_interface2.h.

#define egsRandomInit F77_OBJ_(egs_init_rng,EGS_INIT_RNG)

Shorthand notation for the egs_init_rng function

Definition at line 791 of file egs_interface2.h.

#define egsRandomGet F77_OBJ_(egs_get_rndm,EGS_GET_RNDM)

Shorthand notation for the egs_get_rndm function

Definition at line 806 of file egs_interface2.h.

#define egsFillRandomArray F77_OBJ_(egs_fill_rndm_array,EGS_GET_RNDM_ARRAY)

Shorthand notation for the egs_fill_rndm_array mortran subroutine

Definition at line 820 of file egs_interface2.h.

#define egsElapsedTime F77_OBJ_(egs_tot_time,EGS_TOT_TIME)

Shorthand notation for the egs_tot_time mortran function

Definition at line 837 of file egs_interface2.h.

#define egsCpuTime F77_OBJ_(egs_etime,EGS_ETIME)

Shorthand notation for the egs_etime mortran function

Definition at line 846 of file egs_interface2.h.

#define egsGetTransportParameter F77_OBJ_(get_transport_parameter,GET_TRANSPORT_PARAMETER)

Shorthand notation for the get_transport_parameter mortran subroutine

Definition at line 855 of file egs_interface2.h.

#define egsHowfar F77_OBJ_(egs_howfar,EGS_HOWFAR)

Shorthand notation for the egs_howfar subroutine

Definition at line 872 of file egs_interface2.h.

#define egsHownear F77_OBJ_(egs_hownear,EGS_HOWNEAR)

Shorthand notation for the egs_hownear subroutine

Definition at line 905 of file egs_interface2.h.

#define egsAusgab F77_OBJ_(egs_ausgab,EGS_AUSGAB)

Shorthand notation for the egs_ausgab subroutine

Definition at line 921 of file egs_interface2.h.

#define egsStartParticle F77_OBJ_(egs_start_particle,EGS_START_PARTICLE)

Shorthand notation for the egs_start_particle subroutine

Definition at line 934 of file egs_interface2.h.

Function Documentation

__extc__ void egsInit	(	int	argc,
		char **	argv
	)

Initializes the EGSnrc mortran back-end.

This function initializes default values for the various cross section options and transport parameter settings, creates a temporary working directory where all user code output is stored at run time, and opens necessary Fortran I/O units. It must be called before accessing any EGSnrc data from user codes written in C. This is not necessary in C++ application classes as the function is called in the EGS_SimpleApplication constructor and from the default implementation of the initEGSnrcBackEnd() function of EGS_AdvancedApplication. argc and argv are the command line arguments.

Referenced by EGS_SimpleApplication::EGS_SimpleApplication().

__extc__ void egsFinish ( void )

Finish a simulation.

This function moves all output generated during the run from the temporary working directory to the user code directory. It must be called from user codes written in C before the program exits. For the C++ interface it is called from the default implementations of EGS_SimpleApplication::finish() and EGS_AdvancedApplication::finishRun().

Referenced by EGS_SimpleApplication::finish(), and EGS_AdvancedApplication::finishRun().

__extc__ EGS_I32 egsAddMedium	(	const char *	medname,
		EGS_I32	length
	)

Add a medium to the list of media.

This function adds the medium named medname to the list of media to the mortran back-end (length is the length of medname). It can be used to add media before calling the egsHatch() function to initialize the cross section data. In the C++ interface media found in the geometry are automatically added to the EGSnrc mortran back-end by the EGS_SimpleApplication constructor and by the EGS_AdvancedApplication::initCrossSections() function.

Referenced by EGS_SimpleApplication::EGS_SimpleApplication(), and EGS_AdvancedApplication::helpInit().

__extc__ void egsHatch ( void )

Initialize cross section data from a PEGS4 data file.

This function must be called from user codes written in C after all media are defined (i.e. added using egsAddMedium()) and before the first call to egsShower(). to initialize the cross section data needed at run time from a PEGS4 data file. In the C++ interface this function is automatically called by the EGS_SimpleApplication constructor and by the default implementation of EGS_AdvancedApplication::initCrossSections().

Referenced by EGS_SimpleApplication::EGS_SimpleApplication(), and EGS_AdvancedApplication::helpInit().

__extc__ void egsShower ( void )

Transport the particles currently on the particle stack.

This function transports all particles currently on the particle stack (see EGS_Stack and the_stack). To use it, fill the particle stack the_stack with one or more particles and call it. For user codes written in C++ this function is only relevant if the user wishes to re-implement the EGS_AdvancedApplication::shower() function.

Referenced by EGS_SimpleApplication::run(), and EGS_AdvancedApplication::shower().

__extc__ void egsRandomDefaultInit ( )

Initialize the EGSnrc RNG using default values.

This function should only be used from user codes written in C. Application classes derived from EGS_SimpleApplication or EGS_AdvancedApplication should use EGS_SimpleApplication::rndm or EGS_AdvancedApplication::rndm instead, or construct their own RNG object

__extc__ void egsRandomInit	(	const EGS_I32 *	s1,
		const EGS_I32 *	s2
	)

Initialize the EGSnrc RNG.

This function initializes the EGSnrc RNG. It should only be used from user codes written in C. C++ applications should use EGS_RandomGenerator objects instead. The meaning of the parameters s1 and s2 depends on the RNG being used (RANMAR vs RANLUX). If RANLUX is used, s1 is the luxury level, s2 the initial seed. For RANMAR, the two arguments are initial seeds.

__extc__ void egsRandomGet ( EGS_Float * ranno )

Get a single random number stored at the location pointed to by ranno.

This function should only be used from the C interface, where egsRandomInit() or egsRandomDefaultInit() must have been called before its first use. C++ application should use EGS_RandomGenerator objects instead, either EGS_SimpleApplication::rndm or EGS_AdvancedApplication::rndm or their own RNG object.

__extc__ void egsFillRandomArray	(	const EGS_I32 *	n,
		EGS_Float *	rarray
	)

Get n random numbers stored in the array pointed to by rarray.

This function should only be used from the C interface after the RNG has been initialized using egsRandomInit() or egsRandomDefaultInit(). C++ objects should use EGS_RandomGenerator objetcs instead, either EGS_SimpleApplication::rndm or EGS_AdvancedApplication::rndm or their own RNG object.

Definition at line 1319 of file egs_advanced_application.cpp.

References EGS_SimpleApplication::fillRandomArray().

__extc__ EGS_Float egsElapsedTime ( int * flag )

Get elapsed time.

This function returns the elapsed time in seconds since the last call (if flag = 0) or since the first call (if flag = 1).

__extc__ EGS_Float egsCpuTime ( void )

Get the CPU time used since the process started.

A better way to measure the CPU time in C++ applications is to use an EGS_Timer object.

__extc__ void egsGetTransportParameter ( const int * ounit )

Get the transport parameter settings from the input file.

This function gets transport parameters related input from a section in the input file delimited by :start MC transport parameter: :stop MC transport parameter: The settings are echoed to the Fortran IO unit ounit. In C++ applications a better way to parse the input file is to use an EGS_Input object.

Referenced by EGS_SimpleApplication::EGS_SimpleApplication().

__extc__ void egsHowfar ( void )

Calculate distance to the next boundary along the current direction of motion.

This function must be implemented in user codes written in C. (implementation is automatically provided for C++ applications deriving from EGS_SimpleApplication or EGS_AdvancedApplication). The intended step length is available in the_epcont->ustep, particle position, direction, region number, etc. from the top particle on the particle stack the_stack. This function must calculate the distance t to the next boundary along the particle direction and

If t > the_epcont->ustep, just return
If t <= the_epcont->ustep, set the_epcont->ustep to t, set the_epcont->irnew to the new region index and set the_useful->medium_new to the new medium. If you wish to have a transport cutoff higher than the particle production threshold of the medium in the region, set the_bounds->ecut_new or the_bounds->pcut_new to the desired value(depending on particle charge). If the current particle is an electron and you want to restrict the step size in the new region, set the_etcontrol->smax_new to the desired value. If you want to have a non-default mass density in the new region, set the_useful->rhor_new to the desired value (ratio of desired mass density to the default mass density).
If you want to discard the particle immediately, set the_useful->idisc to a positive value.
If you want to discard the particle after the step is completed, set the_useful->idisc to a negative value.

Definition at line 1264 of file egs_advanced_application.cpp.

References egsWarning, EGS_SimpleApplication::howfar(), EGS_Epcont::idisc, EGS_Stack::ir, EGS_Epcont::irnew, EGS_Useful::medium_new, EGS_Stack::np, the_epcont, the_stack, the_useful, EGS_Stack::u, EGS_Epcont::ustep, EGS_Stack::v, EGS_Stack::w, EGS_Stack::x, EGS_Stack::y, and EGS_Stack::z.

__extc__ void egsHownear ( EGS_Float * tperp )

Calculate minimum perpendicular distance to any surrounding boundary and return it in tperp.

This function must be implemented by user codes written in C (implementation is automatically provided for C++ applications deriving from EGS_SimpleApplication or EGS_AdvancedApplication). If it is impossible to calculate tperp, you must set tperp to 0. In this case the transport will be determined by the setings of EGS_EtControl::transport_algorithm, EGS_EtControl::bca_algorithm and EGS_EtControl::skin_depth_for_bca (see PIRS-701 for details).

Definition at line 1311 of file egs_advanced_application.cpp.

References EGS_SimpleApplication::hownear(), EGS_Stack::ir, EGS_Stack::np, the_stack, EGS_Stack::x, EGS_Stack::y, and EGS_Stack::z.

__extc__ void egsAusgab ( EGS_I32 * iarg )

User scoring function.

This function must be implemented by user codes written in C to perform the actual scoring. The value of iarg depends on the event that triggered the call (see PIRS-701 for details). C++ applications deriving from EGS_SimpleApplication or EGS_AdvancedApplication must implement the respective ausgab() virtual function.

Definition at line 1328 of file egs_advanced_application.cpp.

References EGS_SimpleApplication::ausgab(), EGS_Stack::E, EGS_Stack::iq, EGS_Stack::ir, EGS_Stack::latch, EGS_Stack::np, the_stack, EGS_Stack::u, EGS_Stack::v, EGS_Stack::w, EGS_Stack::wt, EGS_Stack::x, EGS_Stack::y, and EGS_Stack::z.

__extc__ void egsStartParticle ( void )

Start the transport of a new particle.

This function is called just before the transport of a new particle begins (this may be either directly a source particle or just the next particle on the stack). User codes written in C must implement this function to set

the_useful->medium to the medium in the region the particle is in.
the_useful->rhor to the ratio of the region mass density to the default mass density (if you want to use a non-default mass density)
the_bounds->ecut or the_bounds->pcut to the transport cut-off energy (depending on the particle charge). Note that e/pcut must be greater than, or equal to, the_thresh->ae/p of the current medium
the_etcontrol->smaxir to the maximum geometrical step-size restriction, if the particle is an electron and you wish to impose such restrictions. Simple C++ applications deriving from EGS_SimpleApplication can not have a region-by-region variation of transport threshold energies, smax or non-default mass densities and an implementation is automatically provided. An implementation is also provided for advanced C++ applications deriving from EGS_AdvancedApplication. Such applications can implement region-by-region variation of these quantities by re-implementing EGS_AdvancedApplication::startNewParticle().

Definition at line 1343 of file egs_advanced_application.cpp.

References EGS_SimpleApplication::getMedium(), EGS_Epcont::idisc, EGS_Stack::ir, EGS_Useful::medium, EGS_Stack::np, the_epcont, the_stack, and the_useful.

Classes

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

Function Documentation