How to Generate a new cooling table to Use

[YaoguangPei]

Hi all,
Recently, I have been using the turbulence module together with the cooling module. However, I found that the current cooling table is not compatible with my research, as the maximum density covered by the table is too low for my simulation.
Therefore, I would like to generate a new cooling table for my work. Unfortunately, I am not familiar with the procedure. Could you please give me some guidance on how to generate a new cooling table? A rough outline of the process would be greatly appreciated.
In addition, I would like to ask which cooling and heating processes are currently included in the existing cooling table.
Thank you very much for your time and help.
Best regards,
Yaoguang Pei

[dosubot[bot]]

To generate a new cooling table with a higher maximum density, use the script extern/cooling/resample_grackle_cooling_tables.py. This script resamples Grackle/Cloudy cooling data onto a 2D grid of density and specific internal energy, and lets you customize the density range, grid resolution, metallicity, and included physical processes.

Basic outline:

1. Make sure you have Python and the required dependencies (including h5py, numpy, scipy, matplotlib) installed.

2. Run the script from the extern/cooling directory. For example, to generate a table with more density points and a higher density range:

   ./resample_grackle_cooling_tables.py --n_rho 50 --n_eint 400 --output my_cooling_table.h5
   

   • Use --n_rho to set the number of density grid points (increase this and check the source Grackle/Cloudy table covers your desired density range).
   • Use --n_eint to set the number of specific internal energy points.
   • Use --zmet to set metallicity (e.g., --zmet 1.0 for solar).
   • Use --exclude_pe to exclude photoelectric heating (if you want to add it separately).
   • Use --shield to include self-shielding effects.
   • If you want to use a custom Grackle/Cloudy table with a wider density range, provide its path as the first argument.

3. The script outputs an HDF5 file with the required structure and a phase plot of cooling length. The file contains grids for density and energy, and datasets for cooling rates, temperatures, sound speeds, pressures, entropies, and metadata (including whether photoelectric heating is included) example and details.

4. In your simulation input file, set:

   cooling.cooling_table_type = resampled
   cooling.hdf5_data_file = "path/to/my_cooling_table.h5"
   

Physical processes included:
The cooling table includes net cooling and heating rates from:

• Metal line cooling and heating
• Primordial (atomic/molecular) cooling and heating
• Photoelectric heating (if not excluded, based on Wolfire et al. 2003 ISRF)
• Compton cooling from CMB photons

You can control inclusion of photoelectric heating and self-shielding via script flags. The rates are computed as functions of density, temperature, and metallicity see code details.

If you need to cover a higher density range than the default, make sure your input Grackle/Cloudy table supports it, or generate one with the desired range before resampling.

Let me know if you need more details on any step!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[YaoguangPei]

So does this mean that if I want to generate a grid with a higher density upper limit, I must regenerate the cooling table using Cloudy? If so, are there any specific requirements or constraints on the grid that I generate? @dosu

[dosubot[bot]]

Yes, if you need a cooling table with a higher density upper limit, you do need to regenerate the Cloudy (or Grackle) table to cover your desired density range—the resampling script cannot extrapolate beyond the bounds of the input table see details.

For the input grid, the main requirements are: it must cover the full density and temperature range you need, be in HDF5 format, and include datasets for cooling, heating, and mean molecular weight, with grid parameters for density and temperature (typically a 2D grid). The grid dimensionality must not exceed the code’s maximum (usually 2D: density × temperature) reference.

When you run the resampling script, it will construct the output grid to exactly match the min/max bounds of your input table. You can control the grid resolution (number of points in density and energy) via script parameters like --n_rho and --n_eint reference.

So, the practical workflow is: generate your Cloudy/Grackle table with the desired density and temperature range, make sure it includes all relevant physical processes, save it in HDF5 format, and then use the resampling script to produce the final cooling table for Quokka.

Let me know if you want example Cloudy input parameters or help with the resampling script usage!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[YaoguangPei]

Could you provide an example Cloudy input file?@dosu

[dosubot[bot]]

Here’s a generic example Cloudy input file for generating a cooling table suitable for Quokka. You’ll want to adjust the density and temperature ranges, metallicity, and radiation field to match your simulation needs.

# Example Cloudy input file for cooling table generation

# Set hydrogen density grid (logarithmic, e.g., from 1e-6 to 1e4 cm^-3)
grid nH range 1e-6 to 1e4 step 0.2 log

# Set temperature grid (logarithmic, e.g., from 10 K to 1e9 K)
grid temperature range 10 to 1e9 step 0.1 log

# Set metallicity (1.0 = solar, 0.1 = 1/10 solar, etc.)
metals 1.0 log

# Specify the UV background or radiation field (e.g., Haardt & Madau 2012 at z=0)
table HM12 redshift 0

# Include cosmic microwave background
cmb

# Enable/disable physical processes as needed
# To include photoelectric heating:
# grains ISM

# To include self-shielding (optional, if desired):
# set H2 abundance 0
# set shielding on

# Save the cooling and heating rates, and mean molecular weight
save cooling "cooling.out"
save heating "heating.out"
save mean "mmw.out"

# End of input

• Adjust the grid nH and grid temperature lines to cover the full density and temperature range needed for your simulation.
• Set metals to your desired metallicity.
• Use the appropriate table command for your UV background or radiation field.
• Uncomment or add lines for photoelectric heating or self-shielding if needed.

After running Cloudy with this input, you’ll need to convert the output ASCII tables (cooling.out, heating.out, mmw.out) into the required HDF5 format with datasets for log hydrogen number density, temperature, cooling, heating, and mean molecular weight. If Cloudy does not natively output HDF5, you can use or adapt conversion scripts (such as those in the Quokka repo) to build the final table for Quokka’s resampling workflow details.

Let me know if you want more details on the conversion step or specific parameter recommendations!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[markkrumholz]

Just to add to what the bot is saying: if you want to go to higher density, you might also think a bit about the underlying physical model for cooling you want to implement. The cloudy cooling tables that we currently have in the code are intended for simulations targeting the diffuse to somewhat molecular ISM, but likely become increasingly unphysical at densities >> 100 cm^-3. That is because at these higher densities one needs to worry about things like CO cooling in the optically thick regime and dust-gas collisional coupling, physics that it is not trivial to include in a one-zone cloudy-type model. So before you worry about the technical aspects of generating a table, you might want to pause to decide what physical model of thermodynamics you want to implement. If you can tell me a bit more about your intended application, I can try to point you in the right direction.

[YaoguangPei]

Dear Professor,
Thank you for your reply.
My current simulation work focuses on turbulence in ISM. The mean density of the simulation is about 50 m_H cm⁻³. After enabling self-gravity, dense self-gravitating clouds form, with densities that can greatly exceed 100 cm⁻³. I would like the gas in these regions to be able to cool down to temperatures of order 10 K. Therefore, when generating cooling tables with Cloudy, I plan to include CO cooling as well as dust–gas collisional coupling.
Thank you very much for your time and guidance.
Best regards,
Yaoguang Pei

[markkrumholz]

The mean density of the simulation is about 50 m_H cm⁻³. After enabling self-gravity, dense self-gravitating clouds form, with densities that can greatly exceed 100 cm⁻³. I would like the gas in these regions to be able to cool down to temperatures of order 10 K. Therefore, when generating cooling tables with Cloudy, I plan to include CO cooling as well as dust–gas collisional coupling.

If you want to include both atomic regions with lower density that are dominated by atomic cooling and molecular regions dominated by CO cooling, and you're not following explicit chemistry, you will need to adopt some sort of physical model for where the transition from molecular to atomic composition occurs. This is not something that you can simply do with a cloudy one-zone model, because the atomic-molecular transition is mediated by radiative shielding effects that cannot be captured in a one-zone model. If you want to model the atomic-molecular transition somehow, you probably need to adopt some sort of local approximation for the amount of shielding, which you can in turn use to estimate the chemical state of the gas. Cooling is downstream from that. There is a pretty large literature about how to do this, at a variety of levels of sophistication. Some papers I can recommend starting with:

• Clark+ 2012
• Bate & Keto 2015
• Safranek-Shrader+ 2017

These will give you an overview of the different ways people have attempted to come up with thermodynamics approximations that can work in simulations that do not include explicit radiative transfer and photochemistry.

[YaoguangPei]

Dear Prof. Krumholz,
Thank you very much for your reply.
So my understanding is that I need some form of chemical model, even if approximate, to determine the state of the gas, and then, depending on that state, apply cooling tables that include different dominant cooling mechanisms.
Do I understand this correctly?
Thank you again for your time and guidance.
Best regards,
Yaoguang Pei

[markkrumholz]

Yes, that's correct. In the low-temperature, high-density regime, the cooling rate depends critically on the chemical state of the gas. Once you know that, you can implement a model for how the gas cools.

[YaoguangPei]

Dear Prof. Krumholz,
Thank you for your reply.
I sincerely appreciate your kindness and time.
Best regards,
Yaoguang Pei