IAEAphsp/iaea_phsp/iaea_phsp.h

0001
0002 /*
0003  * INTERFACE FOR IAEA PHSP ROUTINES (CONTAINS ONLY DECLARATIONS)
0004  *
0005  * Copyright (C) 2006 International Atomic Energy Agency
0006  * -----------------------------------------------------------------------------
0007  *
0008  * Permission is hereby granted, free of charge, to any person obtaining a copy
0009  * of this software and associated documentation files (the "Software"), to deal
0010  * in the Software without restriction, including without limitation the rights
0011  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
0012  * copies of the Software, and to permit persons to whom the Software is furnished
0013  * to do so, subject to the following conditions:
0014  *
0015  * The above copyright notice and this permission notice shall be included in all
0016  * copies or substantial portions of the Software.
0017  *
0018  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0019  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0020  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
0021  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
0022  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
0023  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
0024  * THE SOFTWARE.
0025  *
0026  *-----------------------------------------------------------------------------
0027  *
0028  *   AUTHORS:
0029  *
0030  *   Roberto Capote Noy, PhD
0031  *   e-mail: R.CapoteNoy@iaea.org (rcapotenoy@yahoo.com)
0032  *   International Atomic Energy Agency
0033  *   Nuclear Data Section, P.O.Box 100
0034  *   Wagramerstrasse 5, Vienna A-1400, AUSTRIA
0035  *   Phone: +431-260021713; Fax: +431-26007
0036  *
0037  *   Iwan Kawrakow, PhD
0038  *   e-mail iwan@irs.phy.nrc.ca
0039  *   Ionizing Radiation Standards
0040  *   Institute for National Measurement Standards
0041  *   National Research Council of Canada Ottawa, ON, K1A 0R6 Canada
0042  *   Phone: +1-613-993 2197, ext.241; Fax: +1-613-952 9865
0043  *
0044  **********************************************************************************
0045  * For documentation
0046  * see http://www-nds.iaea.org/reports-new/indc-reports/indc-nds/indc-nds-0484.pdf
0047  **********************************************************************************/
0048
0049 #ifndef IAEA_PHSP
0050 #define IAEA_PHSP
0051
0052 #include "iaea_config.h"
0053
0054 /************************************************************************
0055 * Initialization
0056 *
0057 * Given a file name header_file of length hf_length, initialize a
0058 * new IAEA particle source, assign an unique source_ID to it and return
0059 * this Id in result. Dont assume header_file is null-terminated as the
0060 * function may be called from a Fortran program.
0061 * The need for an Id arises from the fact that some applications may
0062 * want to use several IAEA sources at once. The implementation must therefore
0063 * maintain a list of already initialized sources.
0064 * If an error occures (e.g. header file does not exist, there are errors
0065 * in the header file, etc.), assign a negative number to result.
0066 * (one may want to specify a list of error codes so that the application
0067 * knows what went wrong). This function *must* be called before using
0068 * any of the following functions for a given source id.
0069 *
0070 * access = 1 => opening read-only file
0071 * access = 2 => opening file for writing
0072 * access = 3 => opening file for appending/updating
0073 *
0074 ***********************************************************************/
0075 IAEA_EXTERN_C IAEA_EXPORT
0076 void iaea_new_source(IAEA_I32 *source_ID, char *header_file,
0077                      const IAEA_I32 *access, IAEA_I32 *result,
0078                      int hf_length);
0079
0080 /************************************************************************
0081 * Maximum number of particles
0082 *
0083 * Set n_particle to the maximum number of particle of type type the
0084 * source with Id id can return. If type<0, set n_particle to the
0085 * total number of all particles. For event generators, this function
0086 * should set n_particle to the maximum integer that can be stored in a
0087 * signed 64 bit integer. If the source with Id id does not exist,
0088 * set n_particle to a negative number.
0089 *************************************************************************/
0090 IAEA_EXTERN_C IAEA_EXPORT
0091 void iaea_get_max_particles(const IAEA_I32 *id, const IAEA_I32 *type,
0092                              IAEA_I64 *n_particle);
0093
0094 /************************************************************************
0095 * Maximum energy
0096 *
0097 * Return the maximum energy of an initialized IAEA source with Id id
0098 * in Emax. Set Emax to negative if a source with that Id does not exist.
0099 ************************************************************************/
0100 IAEA_EXTERN_C IAEA_EXPORT
0101 void iaea_get_maximum_energy(const IAEA_I32 *id, IAEA_Float *Emax);
0102
0103 /*************************************************************************
0104 * Number of additional floats and integers returned by the source
0105 *
0106 * Return the number of additional floats in n_extra_float and the number
0107 * of additional integers in n_extra_integer for the source with Id id.
0108 * Set n_extra_integer and/or n_extra_float to be negative if such a
0109 * source does not exist.
0110 *************************************************************************/
0111 IAEA_EXTERN_C IAEA_EXPORT
0112 void iaea_get_extra_numbers(const IAEA_I32 *id, IAEA_I32 *n_extra_float,
0113                             IAEA_I32 *n_extra_int);
0114
0115 /*************************************************************************
0116 * Number of additional floats and integers to be stored
0117 *
0118 * Set the number of additional floats in n_extra_float and the number
0119 * of additional integers in n_extra_integer for the source with Id id
0120 * to be stored in the corresponding file.
0121 *************************************************************************/
0122 IAEA_EXTERN_C IAEA_EXPORT
0123 void iaea_set_extra_numbers(const IAEA_I32 *id, IAEA_I32 *n_extra_float,
0124                                   IAEA_I32 *n_extra_int);
0125
0126 /*******************************************************************************
0127 * Set a type type of the extra long variable corresponding to the "index" number
0128 * for a corresponding header of the phsp "id". Index is running from zero.
0129 *
0130 * The current list of types for extra long variables is:
0131 *   0: User defined generic type
0132 *   1: Incremental history number (EGS,PENELOPE)
0133 *      = 0 indicates a nonprimary particle event
0134 *      > 0 indicates a primary particle. The value is equal to the number of
0135 *          primaries particles employed to get to this history after the last
0136 *          primary event was recorded.
0137 *   2: LATCH (EGS)
0138 *   3: ILB5 (PENELOPE)
0139 *   4: ILB4 (PENELOPE)
0140 *   5: ILB3 (PENELOPE)
0141 *   6: ILB2 (PENELOPE)
0142 *   7: ILB1 (PENELOPE)
0143 *   more to be defined
0144 *
0145 * Usually called before writing phsp header to set the type of extra long
0146 * variables to be stored. It must be called once for every extralong variable.
0147 *
0148 * type = -1 means the source's header file does not exist
0149 *           or source was not properly initialized (call iaea_new_...)
0150 * type = -2 means the index is out of range ( 0 <= index < NUM_EXTRA_LONG )
0151 * type = -3 means the type to be set is out of range
0152 *           ( 1 <= type < MAX_NUMB_EXTRALONG_TYPES )
0153 *******************************************************************************/
0154 IAEA_EXTERN_C IAEA_EXPORT
0155 void iaea_set_type_extralong_variable(const IAEA_I32 *id,
0156                                       const IAEA_I32 *index,
0157                                             IAEA_I32 *type);
0158
0159 /********************************************************************************
0160 * Set a type type of the extra float variable corresponding to the "index" number
0161 * for a corresponding header of the phsp "id". Index is running from zero.
0162 *
0163 * The current list of types for extra float variables is:
0164 *   1: XLAST (x coord. of the last interaction)
0165 *   2: YLAST (y coord. of the last interaction)
0166 *   3: ZLAST (z coord. of the last interaction)
0167 *   more to be defined
0168 *
0169 * Usually called before writing phsp header to set the type of extra float
0170 * variables to be stored. It must be called once for every extra float variable.
0171 *
0172 * type = -1 means the source's header file does not exist
0173 *           or source was not properly initialized (call iaea_new_...)
0174 * type = -2 means the index is out of range ( 0 <= index < NUM_EXTRA_FLOAT )
0175 * type = -3 means the type to be set is out of range
0176 *           ( 1 <= type < MAX_NUMB_EXTRAFLOAT_TYPES )
0177 *******************************************************************************/
0178 IAEA_EXTERN_C IAEA_EXPORT
0179 void iaea_set_type_extrafloat_variable(const IAEA_I32 *id,
0180                                        const IAEA_I32 *index,
0181                                              IAEA_I32 *type);
0182
0183 /****************************************************************************
0184 * Get a type type of all extra variables from a header of the phsp "id".
0185 *
0186 * extralong_types[] AND extrafloat_types[] must have a dimension bigger than
0187 * MAX_NUMB_EXTRALONG_TYPES and MAX_NUMB_EXTRAFLOAT_TYPES correspondingly
0188 *
0189 * The current list of types for extra long variables is:
0190 *   0: User defined generic type
0191 *   1: Incremental history number (EGS,PENELOPE)
0192 *      = 0 indicates a nonprimary particle event
0193 *      > 0 indicates a primary particle. The value is equal to the number of
0194 *          primaries particles employed to get to this history after the last
0195 *          primary event was recorded.
0196 *   2: LATCH (EGS)
0197 *   3: ILB5 (PENELOPE)
0198 *   4: ILB4 (PENELOPE)
0199 *   5: ILB3 (PENELOPE)
0200 *   6: ILB2 (PENELOPE)
0201 *   7: ILB1 (PENELOPE)
0202 *   more to be defined
0203 *
0204 * The current list of types for extra float variables is:
0205 *   1: XLAST (x coord. of the last interaction)
0206 *   2: YLAST (y coord. of the last interaction)
0207 *   3: ZLAST (z coord. of the last interaction)
0208 *   more to be defined
0209 *
0210 * Usually called before reading phsp header to know the type of extra long
0211 * variables to be read. It must be called once for every extra float variable.
0212 *
0213 * result = -1 means the source's header file does not exist
0214 *             or source was not properly initialized (call iaea_new_...)
0215 *******************************************************************************/
0216 IAEA_EXTERN_C IAEA_EXPORT
0217 void iaea_get_type_extra_variables(const IAEA_I32 *id, IAEA_I32 *result,
0218       IAEA_I32 extralong_types[], IAEA_I32 extrafloat_types[]);
0219
0220 /*************************************************************************
0221 * Set variable corresponding to the "index" number to a "constant" value
0222 * for a corresponding header of the phsp "id". Index is running from zero.
0223 *
0224 *       (Usually called as needed before MC loop started)
0225 *
0226 *                index  =  0 1 2 3 4 5 6
0227 *          corresponds to  x,y,z,u,v,w,wt
0228 *
0229 * Usually called before writing phsp files to set those variables which
0230 * are not going to be stored. It must be called once for every variable
0231 *
0232 * constant = -1 means the source's header file does not exist
0233 *               or source was not properly initialized (call iaea_new_...)
0234 * constant = -2 means the index is out of range ( 0 <= index < 7 )
0235 *************************************************************************/
0236 IAEA_EXTERN_C IAEA_EXPORT
0237 void iaea_set_constant_variable(const IAEA_I32 *id, const IAEA_I32 *index,
0238                                 IAEA_Float *constant);
0239
0240 /*************************************************************************
0241 * Get value of constant corresponding to the "index" number
0242 * for a corresponding header of the phsp "id". Index is running from zero.
0243 *
0244 *                index  =  0 1 2 3 4 5 6
0245 *          corresponds to  x,y,z,u,v,w,wt
0246 *
0247 * Usually called when reading phsp header info.
0248 * It must be called once for every variable
0249 *
0250 *  result = -1 means the source's header file does not exist
0251 *               or source was not properly initialized (call iaea_new_...)
0252 *  result = -2 means the index is out of range ( 0 <= index < 7 )
0253 *  result = -3 means that the parameter indicated by index is not a constant
0254 *************************************************************************/
0255 IAEA_EXTERN_C IAEA_EXPORT
0256 void iaea_get_constant_variable(const IAEA_I32 *id, const IAEA_I32 *index,
0257                                  IAEA_Float *constant, IAEA_I32 *result);
0258
0259 /*****************************************************************************
0260 * Get n_indep_particles number of statistically independent particles read
0261 * so far from the Source with Id id.
0262 *
0263 * Set n_indep_particles to negative if such source does not exist.
0264 ******************************************************************************/
0265 IAEA_EXTERN_C IAEA_EXPORT
0266 void iaea_get_used_original_particles(const IAEA_I32 *id,
0267                                             IAEA_I64 *n_indep_particles);
0268
0269 /*****************************************************************************
0270 * Get Total Number of Original Particles from the Source with Id id.
0271 *
0272 * For a typical linac it should be equal to the total number of electrons
0273 * incident on the primary target.
0274 *
0275 * Set number_of_original_particles to negative if such source does not exist.
0276 ******************************************************************************/
0277 IAEA_EXTERN_C IAEA_EXPORT
0278 void iaea_get_total_original_particles(const IAEA_I32 *id,
0279                                              IAEA_I64 *number_of_original_particles);
0280
0281 /*****************************************************************************
0282 * Set Total Number of Original Particles for the Source with Id id.
0283 *
0284 * For a typical linac it should be equal to the total number of electrons
0285 * incident on the primary target.
0286 *
0287 * Set number_of_original_particles to negative if such source does not exist.
0288 ******************************************************************************/
0289 IAEA_EXTERN_C IAEA_EXPORT
0290 void iaea_set_total_original_particles(const IAEA_I32 *id,
0291                                        IAEA_I64 *number_of_original_particles);
0292
0293 /**************************************************************************
0294 * Partitioning for parallel runs
0295 *
0296 * i_parallel is the job number, i_chunk the calculation chunk,
0297 * n_chunk the total number of calculation chunks. This function
0298 * should divide the available phase space of source with Id id
0299 * into n_chunk equal portions and from now on deliver particles
0300 * from the i_chunk-th portion. (i_chunk must be between 1 and n_chunk)
0301 * The extra parameter i_parallel is needed
0302 * for the cases where the source is an event generator and should
0303 * be used to adjust the random number sequence.
0304 * The variable is_ok should be set to 0 if everything went smoothly,
0305 * or to some error code if it didnt.
0306 **************************************************************************/
0307 IAEA_EXTERN_C IAEA_EXPORT
0308 void iaea_set_parallel(const IAEA_I32 *id, const IAEA_I32 *i_parallel,
0309                        const IAEA_I32 *i_chunk, const IAEA_I32 *n_chunk,
0310                        IAEA_I32 *is_ok);
0311
0312 /**************************************************************************
0313 * setting the pointer to a user-specified record no. in the file
0314 *
0315 * record_num is the user-specified record number passed to the function.
0316 * id is the phase space file identifier.
0317 * The variable result should be set to 0 if everything went smoothly,
0318 * or to some error code if it didnt.
0319 **************************************************************************/
0320 IAEA_EXTERN_C IAEA_EXPORT
0321 void iaea_set_record(const IAEA_I32 *id, const IAEA_I64 *record_num,
0322                            IAEA_I32 *result);
0323
0324 /**************************************************************************
0325 * check that the file size equals the value of checksum in the header
0326 *
0327 * id is the phase space file identifier.  If the size of the phase space
0328 * file is not equal to checksum, then result returns -1, otherwise result
0329 * is set to 0.
0330 **************************************************************************/
0331 IAEA_EXTERN_C IAEA_EXPORT
0332 void iaea_check_file_size_byte_order(const IAEA_I32 *id, IAEA_I32 *result);
0333
0334 /**************************************************************************
0335 * Get a particle
0336 *
0337 * Return the next particle from the sequence of particles from source
0338 * with Id id. Set n_stat to the number of statistically independent
0339 * events since the last call to this function (i.e. n_stat = 0, if
0340 * the particle resulted from the same incident electron, n_stat = 377
0341 * if there were 377 statistically independent events sinc the last particle
0342 * returned, etc.). If this information is not available,
0343 * simply set n_stat to 1 if the particle belongs to a new statistically
0344 * independent event. Set n_stat to -1, if a source with Id id does not
0345 * exist. Set n_stat to -2, if end of file of the phase space source reached
0346 **************************************************************************/
0347 IAEA_EXTERN_C IAEA_EXPORT
0348 void iaea_get_particle(const IAEA_I32 *id, IAEA_I32 *n_stat,
0349 IAEA_I32 *type, /* particle type */
0350 IAEA_Float *E,  /* kinetic energy in MeV */
0351 IAEA_Float *wt, /* statistical weight */
0352 IAEA_Float *x,
0353 IAEA_Float *y,
0354 IAEA_Float *z,  /* position in cartesian coordinates*/
0355 IAEA_Float *u,
0356 IAEA_Float *v,
0357 IAEA_Float *w,  /* direction in cartesian coordinates*/
0358 IAEA_Float *extra_floats,
0359 IAEA_I32 *extra_ints);
0360
0361 /**************************************************************************
0362 * Write a particle
0363 * n_stat = 0 for a secondary particle
0364 * n_stat > 0 for an independent particle
0365 *
0366 * Write a particle to the source with Id id.
0367 * Set n_stat to -1, if ERROR (source with Id id does not exist).
0368 **************************************************************************/
0369 IAEA_EXTERN_C IAEA_EXPORT
0370 void iaea_write_particle(const IAEA_I32 *id, IAEA_I32 *n_stat,
0371 const IAEA_I32 *type, /* particle type */
0372 const IAEA_Float *E,  /* kinetic energy in MeV */
0373 const IAEA_Float *wt, /* statistical weight */
0374 const IAEA_Float *x,
0375 const IAEA_Float *y,
0376 const IAEA_Float *z,  /* position in cartesian coordinates*/
0377 const IAEA_Float *u,
0378 const IAEA_Float *v,
0379 const IAEA_Float *w,  /* direction in cartesian coordinates*/
0380 const IAEA_Float *extra_floats,
0381 const IAEA_I32 *extra_ints);
0382
0383 /***************************************************************************
0384 * Destroy a source
0385 *
0386 * This function de-initializes the source with Id id, closing all open
0387 * files, deallocating memory, etc. Nothing happens if a source with that
0388 * id does not exist. Header is updated.
0389 ****************************************************************************/
0390 IAEA_EXTERN_C IAEA_EXPORT
0391 void iaea_destroy_source(const IAEA_I32 *source_ID, IAEA_I32 *result);
0392
0393 /***************************************************************************
0394 * Print the current header associated to source id
0395 *
0396 * result is set to negative if phsp source does not exist.
0397 ****************************************************************************/
0398 IAEA_EXTERN_C IAEA_EXPORT
0399 void iaea_print_header(const IAEA_I32 *source_ID, IAEA_I32 *result);
0400
0401 /***************************************************************************
0402 * Copy header of the source_id to the header of the destiny_id
0403 ****************************************************************************/
0404 IAEA_EXTERN_C IAEA_EXPORT
0405 void iaea_copy_header(const IAEA_I32 *source_ID, const IAEA_I32 *destiny_ID,
0406                       IAEA_I32 *result);
0407
0408 /***************************************************************************
0409 * Update header of the source_id
0410 ****************************************************************************/
0411 IAEA_EXTERN_C IAEA_EXPORT
0412 void iaea_update_header(const IAEA_I32 *source_ID, IAEA_I32 *result);
0413
0414 #endif