HII-CHI-mistry-Teff A python script to derive the hardness of the incident ionizing radiation

DESCRIPTION

HII-CHI-mistry-Teff is a python script that calculates the ionization parameter (log U) and the equivalent effective temperature (Teff) using relative emission-line fluxes emitted by ionized gaseous nebulae. The code is described in Perez-Montero et al. (2019, MNRAS, 483, 3322). From version 4 it can also be used to estimate the number of absorbed ionizing photons in a density-bounded geometry (see Perez-Montero et al. (2020, A&A, 643, A80).

Another version of the code calculates the hardness of the field of radiation and U based on the relative fluxes of emission-lines in the mid-IR. This version, called HCm-Teff-IR, is described in Perez-Montero et al. (2024), to calculate Teff in star-forming galaxies, and in Pérez-Montero et al. (submitted) for the derivation of the parameter alpha_OX in AGN.

MOST RECENT VERSION

The most recent version for HII-CHI-mistry-Teff is version 5.5.

Regarding infrared, the most recent version is version 3.0. The links lead to the corresponding compressed tar.gz files containing the python files of the codes, the libraries of the models and a file with instructions. Previous versions of the program can be obtained in the History and Downloads section and they can also be found in GitHub.

How to run it

HII-CHI-mistry-Teff has been originally written in python v. 2.7, but from version 5 is only compatible with python 3 (This holds for the IR version). It requires the library numpy (versions previous to v2.0 use the library asciidata).

The program also requires the files of the emission line intensities predicted by the models, calculated assuming different sets of input conditions. All were calculated with Cloudy v.17. These libraries are stored in the folder Library_Teff and include models for single stars (WM-Basic from 30 kK to 60 kK, and Rauch PNe from 80 kK to 120 kK) and black-body (from 30 kK to 100 kK), both for plane-parallel and spherical geometry. The libraries also include from BPASS v.2.1 to calculate the absorption factor of ionizing photons.

To run the program, just type (for v5.5, in other versions use the name of the corresponding python script:
python HCm-Teff_v5.5.py
Once the input file has been specified in the prompt or by direct question, the code will ask about what quantity must be calculated (Teff or absorption factor) and the used models (assumed SED and geometry).
Later, once selected the model SED, the program will ask for the use of a interpolated high-resolution grid (0: non-interpolated or 1: interpolated). This will increase the resolution of the grid in O/H, Teff or f_abs and log U in a factor 10, but it will slow down the calculation. It is also possible to run the code in non-interactive mode is the variable 'interactive' is set to 'False' in the script.

For the IR version, it is all similar, with the exception that the libraries are stored in a folder called Libraries_Teff-IR. In addition, from version 3 this code can also calculate the shape of the ionizing SED in AGNs, so the first question is about if we want to calculate Teff or alpha_OX. In the latter case, additional questions about the stopping criteria for the models (2%, 98% or 99.9% free electrons) and about the presence or absence of dust grains mixed with the gas in the models will appear before the calculations.

The input file

It is a separated file written in text format with the information organised as a table whose first row contains the labels for the different columns, corresponding to the identification of each row, the metallicity and the emission line fluxes and their errors. The table can contain columns for other quantities, but the code will only read the following labels:

ID for the identification name of the row
'12logOH and e12logOH:: 12+log(O/H) and error
CIV_1549 and eCIV_1549: CIV] 1549 and error
CIII_1909 and eCIII_1909: CIII] 1909 and error
OII_3727 and eOII_3727: [OII] 3727 and error
OIII_4959 and eOIII_4959: for [OIII] 4959 and its error
OIII_5007 and eOIII_5007: for [OIII] 5007 and its error It is possible to give only one of the two strong nebular [OIII] lines.
SII_6725 and eSII_6725: for the sum of [SII] 6716+6731 and the error. It is possible to give the [SII] lines individually too.
SIII_9069 and eSIII_9069: for [SIII] 9069 and its error
SIII_9532 and eSIII_9532: for [SIII] 9069 and its error. It is possible to give only one of the two strong nebular [SIII] lines
HeI_4471 and eHeI_4471: for HeI 4471 and its error
HeI_5876 and eHeI_5876: for HeI 5876 and its error
HeI_6678 and eHeI_6678: for HeI 6678 and its error
HeII_4686 and eHeII_4686: for HeII and its error
ArIII_7135 and eArIII_7135: for [ArIII] 7135 and its error
ArIV_4740 and eArIV_4740: for [ArIV] 4740 and its error
'NII_6584 and eNII_6584: [NII] 6584 and error

The program will only provide a calculation if at least one of the possible low-to-high emission-line ratios is given (e.g. [OII] and [OIII] and/or [SII] and [SIII] and/or HeI and HeII and/or [ArIII] and [ArIV]), although some other combinations also provide a solution (e.g. [SII] and [ArIII], or πNII] and [SIII]). Then, if only two low-excitation or high-excitation lines are given the program will provide 0 values in the results. The lines must be reddening corrected, but it is not necessary to express them in relation to Hß. If metallicity or other line is unknown for all objects the corresponding column has not to be added, but if no information can be given about a certain line or its error it can be typed as zero.

For the IR version, the possible emission-lines admitted by the code, besides those regarding the ID and the metallicity are:

ArIII_7m and eArIII_7m: [ArIII] 6.98 microns and its error
ArIV_8m and eArIV_8m: [ArIV] 7.90 microns and its error
ArIII_9m and eArIII_9m: [ArIII] 8.99 microns and its error
SIV_10m and eSIV_10m: [SIV] 10.5 microns and its error
NeII_12m and eNeII_12m: [NeII] 12.8 microns and its error
ArV_13m and eArV_13m: [ArV] 13.1 microns and its error
NeV_14m and eNeV_14m: [NeV] 14.9 microns and its error
NeIII_15m and eNeIII_15m: [NeIII] 15.5 microns and its error
SIII_18m and eSIII_18m: [SIII] 18.7 microns and its error
NeV_24m and eNeV_24m: [NeV] 24.3 microns and its error
OIV_25m and eOIeV_25m: [OIV] 25.9 microns and its error
SIII_33m and eSIII_33m: [SIII] 33.7 microns and its error
OIII_52m and eOIII_52m: [OIII] 52 microns and its error
NIII_57m and eNIII_57m: [NIII] 57 microns and its error
OIII_88m and eOIII_88m: [OIII] 88 microns and its error
NII_122m and eNII_122m: [NII] 122 microns and its error
'NII_205m' and 'eNII_205m': [NII] 205 microns and its error

In this case the program will provide a solution for Tef in star-forming regions when two or more low-to-high emission line ratios are provided among [NeII]/[NeIII], [SIII]/[SIV], [OIII]/[OIV] or other involving Ar lines. For AGN is quite similar, but only when a very high-excited line such as [OIV] or [NeV] are involved.

Results

If the input file is correct, the program will ask for the chosen SED and geometry (plane-parallel or spherical) and the use of interpolations and it will begin to calculate the wanted quantities and their corresponding errors.
The information will be displayed on the screen for each object, along with the ratio of completeness of the task.

At the end, the program will create a file called using the name of the input file + "_hcm-output.dat with the information of the used models, the identification of each row, the input emission line fluxes and their errors, the input oxygen abundance, , and four columns with the solutions corresponding to the following information:

T_eff (in K) or f_Abs (in terms of the ratio ionizing absorbed photons over tottal of ionizing photons emitted by the central source; or alpha_OX for AGN in the IR version)
error of T_eff or f_abs
log U
error of log(U

In case of error, a value '-9999' will be inserted in the corresponding row of the output table.

History and Downloads

Here we list the different versions of the program with links to download them for both the optical and the IR version.

HCm-Teff for the optical

version 5.5 (2024/06): A non-interactive mode has been incorporated to speed up the usability of the code. Besides, now, when the code finds an error in the input, it does not stop. Instead, it includes a '9999' in the output. This improves the calculations with large data samples.
Version 5.4 (2023/04): The emission-line ratio CIII] 1909/CIV] 1549 is now accepted as input. Libraries for models calculated using blackbody with t* = 1e5K, equivalent to metal-free massive stars, have been incorporated for the calculation of both the effective temperature and the absorption fraction of photons.
Version 5.3 (2022/07): Now the code also accepts as input [NII] emission lines. According to Perez-Montero et al. (2023a) this can replace [SII], more affected by background diffuse ionized gas.
Version 5.2 (2022/04): Libraries for Rauch post-AGB stars have been incorporate to extend the Teff range of WM-Basic up to 120,000 K. For the calculation of the photon absorption factor libraries from models using BPASS SEDS assuming nearly metal-free stars (e.g. Z = 1e-5) have been also incorporated. Emission lines for HeI 6678 AA, [ArIV] 4740 AA, and [ArIII] 7135 AA can now be used as input.
Version 5.11 (2022/04): Libraries with models are stored in particular folders. Changes in the code to optimize the reading of the files. The output file no longer shows columns with emission lines that were not introduced as inputs. Some bugs found in version 5.1 related with the writing of the output when [SII] and [πSIII] lines are given separately have been fixed. Interpolation for models for the calculation of absorption factor is now allowed.
Version 5.01 (2020/12): Labels for the ID of each row and for the used emission lines can be used, so it is not necessary to give all columns. A bug related with objects with no HeII emission has been fixed.
Version 4.1 (2020/09): Now emission-line of HeI at 4471å can be used. All grids have been extended down to log U = -4.0. Interpolation of the grid of models can be used too.
Version 4.0 (2020/05): Lines of Hei at 5876 and HeII 4686 are now included to better explore high-energy sources (see Pérez-Montero et al. 2020). In addition, the code now includes BPASS v.2.1 density-bounded models and can provide estimates for the absorption fraction of ionizing photons. Te code now also considers ionizing sources from black bodies at different temperatures.
Version 3.1 (2019/09): The code is now compatible with python 3 and some improvement in the error treatment has been added.
Version 3.0 (2019/03): Now the code allows to choose among models calculated using a plane-parallel or a spherical geometry. In addition, the resolution of the grid in ionization parameter has been improved. Now the output file provides more information.
Version 2.0 (2018/05): Version 2.0 calculates errors using a MonteCarlo iteration from the input error line fluxes. The number of iterations can be easily edited in the python file. In addition, the mean of the errors of the Chi-square distribution is quadratically added to the Monte Carlo error. If not, when no errors are introduced for the lines the final error is too small.

HCm-Teff-IR

version 3.0 (2024/09): The code can be also be used to estimate the parameter alpha_OX, representative of the hardness of the incident SED in AGN. This can only be made when [NeV] and [OIV], and the corresponding ratios with the emission lines of lower ionization measured in the mid-IR are given. For more details on this see Pérez-Montero et al (submitted)
version 2.3 (2024/06): A non-interactive mode has been incorporated to speed up the usability of the code. Besides, now, when the code finds an error in the input, it does not stop. Instead, it includes a '9999' in the output. This improves the calculations with large data samples.
HCmTeff-IR version 2.2 (2023/09): Version IR of the code to calculate Teff and U with the same model libraries as computed for the optical version. This is described in Perez-Montero et al. (2024).