Context. Photoionisation is one of the main mechanisms at work in the gaseous environment of bright astrophysical sources. A great deal of information on the gas physics, chemistry and kinematics, and on the ionising source itself, can be gathered through optical to X-ray spectroscopy. While several public time equilibrium photoionisation codes are readily available and can be used to infer average gas properties at equilibrium, time-evolving photoionisation models have only very recently started to become available. They are needed when the ionising source varies faster than the typical gas equilibration timescale. Using equilibrium models to analyse spectra of non-equilibrium photoionised gas may lead to inaccurate results, and prevents a solid assessment of gas density, physics, and geometry.
Aims. Our main objective is to present and make available the Time-Evolving PhotoIonisation Device (TEPID), a new code that self-consistently solves time evolving photoionisation equations (both thermal and ionisation balance) and accurately follows the response of the gas to changes in the ionising source.
Methods. TEPID self-consistently follows the gas temperature and ionisation in time by including all the main ionisation/recombination and heating/cooling mechanisms. The code takes in input the ionising light curve and spectral energy distribution and solves the time-evolving equations as a function of gas electron density and of time. The running time is intelligently optimised by an internal algorithm that initially scans the input light curve to set a time-dependent integration frequency. The code is built in a modular way, can be applied to a variety of astrophysical scenarios and produces time-resolved gas absorption spectra to fit the data.
Results. To describe the structure and main features of the code, we present two applications of TEPID to two dramatically different astrophysical scenarios: the typical ionised absorbers observed in the X-ray spectra of active galactic nuclei (e.g. warm absorbers and ultra-fast outflows), and the circumburst environment of a gamma-ray burst. For both cases we show how the gas energy and ionisation balances vary as a function of time, gas density and distance from the ionising source. We show that time-evolving photoionisation leads to unique ionisation patterns that cannot be reproduced by stationary photoionisation codes when the gas is out of equilibrium. This demonstrates the need for codes such as TEPID in view of the unprecedented capabilities that will be offered by the upcoming high-resolution X-ray spectrometers on board missions like XRISM or Athena.