/* * return error conditions * many routines are void and return no values. * Those that do return values return an int for the function that indicates success. * A return value of zero (FALSE) indicates that the routine was not successful, and * a positive value (not always 1) indicates success. So the way to obtain a value * and test for success is * * if( !cdRead("Line image") ) * { * . . . error condition handler . . . * } */ /* this will be set true when cdInit is called. * Other routines will check that this is TRUE when they are called, * to verify that cdInit was called first. Definition is in cdDefines.c */ extern int lgcdInitCalled; /* * cddrive.h * definitions for the suite of routines that allow the code to * be driven as a surboutine */ /*********************************************************** * * routines that set up model parameters and * control the execution of Cloudy * ***********************************************************/ /* * cdInit * the routine that must be called first - * it initialialies many variables */ void cdInit(void); /* * cdTalk * tells the code whether or not to produce any of its normal ouput, * int is TRUE (produce output) or FALSE (never say anything) * the defaul if the routine is not called is to produce the normal output */ void cdTalk(int); /* * cdOutp * tells the code where to send output. the argument must be * a previously oppened file. all output will go to this file. * If cdTalk was called with TRUE then all of the standard output will go to * this file. If the routine is not called all output will go to stdout */ void cdOutp(FILE* ); /* * cdRead * sends strings of commands to the code. The normal set of commands * described in Part I of Hazy must be generated by fprintf into null terminated * strings. These strings are fed to cloudy with this command. The function * returns the number of commands that can still be entered before the command * stack fills up. the code will stop if you try to continue giving it commands * after the stack is full. */ int cdRead(char* ); /* * cdNoexec * an option to have the code prepare the initial conditions for a model, * not not actually try to compute the model. I use this when setting up a large * grid, so that I can quickly compute the full grid as a check that the commands * are entered properly and the parameters I am going to vary do so properly. * the command is then commented out when the grid is properly set up. */ void cdNoexec(void); /* * cdDrive * actually computes the model. * It returns 0 if the calculation was successful, and 1 if an error * condition was encountered */ int cdDrive(void); /*********************************************************** * * routines that confirm that the previous calculation is ok * or produce a list of error conditions * ***********************************************************/ /* * cdErrors * after the calculation, a summary of all error messages will be * be generated by calling this routine. the argument is the output device * for the output */ void cdErrors(FILE* ); /* * cdNwcns * returns the number of warnings, cautions, notes, surprises, * temperature failures, and pressure failures, in the last computed model */ void cdNwcns( /* the number of warnings, cautions, notes, and surprises */ long int *NumberWarnings, long int *NumberCautions, long int *NumberNotes, long int *NumberSurprises, /* the number of temperature convergence failures */ long int *NumberTempFailures, /* the number of pressure convergence failures */ long int *NumberPresFailures, /* the number of ionzation convergence failures */ long int *NumberIonFailures, /* the number of electron density convergence failures */ long int *NumberNeFailures ); /* print why the model stopped, ad the model geometry on this io unit */ void cdReasonGeo(FILE*); /* * and produce lists of warnings, cautions, notes, surprises * these are the routines that are called by cdErrors. Normally * cdErrors and not these routines would be called by the user. */ void cdWarnings(FILE*); void cdCautions(FILE*); void cdSurprises(FILE*); void cdNotes(FILE*); /*********************************************************** * * routines that examine the preditions of the previous model * ***********************************************************/ /* * cdLine * find the predicted intensity of any line, * first par is 4-char label (null terminated) label, as it appears in output * second parameter is integer wavelength * 3rd parameter is linear intensity relative to normalization line * 4th par is log of luminosity or intensity of line (ergs) * routine returns pointer (>0) to arrray element within stack if it finds the line, * 0 (==FALSE) otherwise - must be a long int since there are LOTS of lines */ long int cdLine( char *chLabel, long int length, double *relint, double *absint); /* * cdColm * obtain the column density from the previously computed model * first parameter is 4 character + NULL terminated string, the first 4 char of * the element name as spelled by Cloudy. * The second parameter is the stage of ionization, 1 for atom, 2 for first ion, etc * if the ion stage is zero then the routine will check * for the labels "H2 " and "CO ". It will return the H2 or CO col in this case * * the column density is returned as the third parameter in all cases * * The function returns TRUE if it could find the species, FALSE if failure */ int cdColm(char*, long, double* ); /* * cdEms * find the local emissivity for any line * first arg is 4 character (null terminated) label as it appears in the standard output. * second is integer wavelength as it appears in the standard output. * The emissivity (erg /cm^3 /s) is returned as the last parameter. * cdEms returns TRUE if it can find the line, FALSE otherwise */ int cdEms( char *chLabel, long int length, double *emiss ); /* * cdGetCooling * returns the total cooling (erg cm^-3 s^-1) for the last computed zone */ double cdGetCooling(void); /* * cdGetCooling * returns the total heating (erg cm^-3 s^-1) for the last computed zone */ double cdGetHeating(void); /* * cdGetPres * returns the pressure and its constituents, for the last computed zone */ void cdGetPres( /* total pressure, all forms*/ double *TotalPressure, /* gas pressure */ double *GasPressure, /* radiation pressure */ double *RadiationPressure); /* * cdGetTe * returns the temperature of the last computed zone */ double cdGetTe(void); /* * cdGett * read output header from previous version calculation * return value will be set true if we hit eof, * more models later if false */ int cdGett(FILE *); /* * cdIonFrac * returns the ionization fraction for any element included in the calculation * first parameter is 4 char null terminad string giving first 4 letters of * element name as spelled by cloudy. * Second parameter is integer ionization stage, 1 for atom, 2 for first ion, etc. * third parameter is pointer to double variale which will be the ionization fraction * last paramger is 8 character + null string that says either "volume" or "radius", * to specify whether the average should be weighted by volume or radius * return value is flag saying whether element was found - TRUE if successful, * FALSE if failure */ int cdIonFrac( /* four char string, null terminzed, giving the element name */ char *chLabel, /* IonStage is ionization stage, 1 for atom, up to N+1 where N is atomic number */ long int IonStage, /* will be fractional ionization */ double *fracin, /* how to weight the average, must be "VOLUME" or "RADIUS" */ char *chWeight); /* * cdVersion * argument is a string with at least 8 char that will receive a null terminated * string with the version number of the code */ void cdVersion(char chString[] ) ; /* * cdDate * argument is a string with at least 8 char that will receive a null terminated * string with the date of the current version of the code */ void cdDate(char chString[] ) ; /* routines to keep trace of execution time for one model - * cdSetExecTime called first (in cdInit) to initialize timer, * then cdExecTime at end to get ellapsed time in seconds */ void cdSetExecTime(void); /* routine cdExecTime will then return the time since cdInit was called, * its declaration is in cddrive.h and its source in setexectime.c */ /* returns the cpu time (sec) that has elapsed since cdInit was called, * source is in setexectime */ double cdExecTime(void); /* routine to read in master list of emission line wavelengths and ids, for * generating loc grids, data file stored as blrLineList.dat in data dir */ /* it returns the number of lines to be allocated. the selection of lines * in that file is appropriate for a denser gas as in the BLR */ long int cdGetBLRLineList(void); /* wavelength arrays */ extern char ** cdGetchLabel ; extern long int *cdGetnWL; /* * cdTimescales returns thermal, recombination, and H2 foramtion timescales */ void cdTimescales( /* the thermal cooling timescale */ double *TTherm , /* the hydrogen recombination timescale */ double *THRecom , /* the H2 formation timescale */ double *TH2 ); /* read in the FeII Bands file, and return number of bands */ long int cdGetFeIIBands(void); /* band wavelength, lower and upper bounds, in vacuum Angstroms */ /* FeII.bands[n][3], where n is the number of bands in fe2bands.dat * these bands are defined in fe2bands.dat and read in at startup * of calculation */ extern float **FeII_Bands; /* number of bands in fe2bands.dat */ extern long int FeIInBands; /* * this routine returns the spectrum needed for Keith Arnaud's XSPEC * X-Ray analysis code. It should be called after cdDrive has successfully * computed a model. the calling routine must ensure that the three vectors * have enough space to store the resulting spectrum, * given the bounds and energy resolution */ void cdSPEC( /* the type of spectrum to be returned * option==1 the incident continuum 4\pi nuJ_nu, , erg cm-2 s-1 * option==2 the transmitted continuum, same units * option==3 the reflected continuum and lines, same units * option==4 the sum of diffuse lines and continuum emitted by * the cloud, same units assuming full coverage of * continuum source */ int Option , /* the energy of the lower edge of the lowest cell * (in Ryd to be consistent with all the rest of Cloudy) */ double EnergyLow , /* the energy of the upper edge of the highest cell, in Ryd */ double EnergyHigh , /* the width of each cell in Ryd */ double EnergyWidth , /* the returned spectrum (see option) */ double ReturnedSpectrum[] ); /*cdTemp get mean electron temperature for any element */ /* return value is logical flag saying whether element was found, * FALSE not found; TRUE found*/ int cdTemp( /* four char string, null terminzed, giving the element name */ char *chLabel, /* IonStage is ionization stage, 1 for atom, up to N+1 where N is atomic number */ long int IonStage, /* will be temperature */ double *TeMean, /* how to weight the average, must be "VOLUME" or "RADIUS" */ char *chWeight ); /* some macros that will be of use */ #ifndef TRUE #define TRUE 1 #endif /* */ #ifndef FALSE #define FALSE 0 #endif /* */ #ifndef MAX2 /* MAX2 takes two arguments, returns the larger of the two */ #define MAX2(a,b) (((a)>(b)) ? (a) : (b)) #endif /* */ #ifndef MIN2 /* MIN2 takes two arguments, returns the smaller of the two */ #define MIN2(a,b) (((a)<(b)) ? (a) : (b)) #endif /* */