How to use ucat and ucat_sps

ucat and ucat_sps generates a catalog of galaxies using the ivy workflow engine. We are describing here how to use ucat and ucat_sps without the galsbi interface which enables the user to generate a galaxy catalog with maximum flexibility.

Running plugins directly

The most straightforward way to create a galaxy catalog is by running the corresponding ucat or ucat_sps plugin directly. First, we need to build the context of the simulation. We load the default values from either the galsbi.ucat.config.common or galsbi.ucat_sps.config.common_sps module and assign the correct file paths to others.

import ivy
import os
from cosmo_torrent import data_path

ctx = ivy.context.create_ctx(
    parameters=ivy.load_configs("galsbi.ucat.config.common")
)

# integrations tables, templates, filters and extinction files
ctx.parameters.template_file_name = os.path.join(data_path("template_BlantonRoweis07"), "template_spectra_BlantonRoweis07.h5")
ctx.parameters.filters_file_name = os.path.join(
    data_path("HSC_tables"), "HSC_filters_collection_yfix.h5"
)
ctx.parameters.templates_file_name = os.path.join(
    data_path("template_BlantonRoweis07"), "template_spectra_BlantonRoweis07.h5"
)
ctx.parameters.extinction_map_file_name = os.path.join(
    data_path("lambda_sfd_ebv"), "lambda_sfd_ebv.fits"
)
ctx.parameters.templates_int_tables_file_name = os.path.join(
    data_path("HSC_tables"), "HSC_template_integrals_yfix.h5"
)
from galsbi.ucat.plugins import sample_galaxies

plugin = sample_galaxies.Plugin(ctx)
plugin()

A similar example can be run for ucat_sps. The packaged intrinsic configuration supplies the complete GalSBI-SPS defaults, including the current ProMage resource directory, surviving-stellar-mass models, filters, and extinction map:

ctx = ivy.context.create_ctx(
    parameters=ivy.load_configs(
        "galsbi.configs.config_Tortorelli+25_intrinsic"
    )
)

and we run a different plugin

from galsbi.ucat_sps.plugins import sample_galaxies_sps

plugin = sample_galaxies_sps.Plugin(ctx)
plugin()

The context now contains a galaxy catalogue with parameters such as redshift and apparent magnitudes in different bands. Both workflows apply a magnitude selection while sampling. In GalSBI-SPS, ProMage applies the selection in filters_full_names_prospect_selection at promage_selection_mag_threshold; this preselection is also used when the final magnitudes are generated with ProSpect.

import matplotlib.pyplot as plt
from cosmic_toolbox.colors import set_cycle
set_cycle()

plt.figure(figsize=(3,2))
plt.hist(ctx.galaxies.z, bins=100)
plt.xlabel("$z$")
plt.show()

fig, axs = plt.subplots(1,3, figsize=(6,2), sharex=True, sharey=True)
axs[0].hist(ctx.galaxies.int_magnitude_dict["g"], bins=100)
axs[0].set_xlabel("mag g")
axs[1].hist(ctx.galaxies.int_magnitude_dict["r"], bins=100)
axs[1].set_xlabel("mag r")
axs[2].hist(ctx.galaxies.int_magnitude_dict["i"], bins=100)
axs[2].set_xlabel("mag i");
_images/output_6_0.png _images/output_6_1.png

Running from config files

Basic example

Especially if the pipelines become more complex, it might be easier to generate a config file and run this config file. The script from above would look like this if you setup a config file:

basic_example_config.py
import os
import galsbi.ucat.config.common
from cosmo_torrent import data_path

# Import all common settings from ucat and ufig
for name in [name for name in dir(galsbi.ucat.config.common) if not name.startswith("__")]:
    globals()[name] = getattr(galsbi.ucat.config.common, name)

plugins = ["galsbi.ucat.plugins.sample_galaxies"]
filters_file_name = os.path.join(
    data_path("HSC_tables"), "HSC_filters_collection_yfix.h5"
)
templates_file_name = os.path.join(
     data_path("template_BlantonRoweis07"), "template_spectra_BlantonRoweis07.h5"
 )
extinction_map_file_name = os.path.join(
     data_path("lambda_sfd_ebv"), "lambda_sfd_ebv.fits"
 )
templates_int_tables_file_name = os.path.join(
     data_path("HSC_tables"), "HSC_template_integrals_yfix.h5"
 )

Running this config file is then done by using ivy.execute command. The resulting galaxy distribution is the same as above.

ctx = ivy.execute("basic_example_config")

plt.figure(figsize=(3,2))
plt.hist(ctx.galaxies.z, bins=100)
plt.xlabel("$z$")
plt.show()

fig, axs = plt.subplots(1,3, figsize=(6,2), sharex=True, sharey=True)
axs[0].hist(ctx.galaxies.int_magnitude_dict["g"], bins=100)
axs[0].set_xlabel("mag g")
axs[1].hist(ctx.galaxies.int_magnitude_dict["r"], bins=100)
axs[1].set_xlabel("mag r")
axs[2].hist(ctx.galaxies.int_magnitude_dict["i"], bins=100)
axs[2].set_xlabel("mag i");
_images/output_12_3.png _images/output_12_4.png

Complex example

You can combine different plugins by adapting the config file. This example samples galaxies based on the default values, applies shear to them and saves the catalogs for all bands.

complex_example_config.py
import os
import galsbi.ucat.config.common
from cosmo_torrent import data_path

# Import all common settings from ucat and ufig
for name in [name for name in dir(galsbi.ucat.config.common) if not name.startswith("__")]:
    globals()[name] = getattr(galsbi.ucat.config.common, name)

plugins = [
    "galsbi.ucat.plugins.sample_galaxies",
    "galsbi.ucat.plugins.apply_shear",
    "galsbi.ucat.plugins.write_catalog_photo",
    "galsbi.ucat.plugins.write_catalog",
    "ivy.plugin.show_stats"
]

filters_file_name = os.path.join(
    data_path("HSC_tables"), "HSC_filters_collection_yfix.h5"
)
templates_file_name = os.path.join(
    data_path("template_BlantonRoweis07"), "template_spectra_BlantonRoweis07.h5"
)
extinction_map_file_name = os.path.join(
    data_path("lambda_sfd_ebv"), "lambda_sfd_ebv.fits"
)
templates_int_tables_file_name = os.path.join(
    data_path("HSC_tables"), "HSC_template_integrals_yfix.h5"
)

filepath_tile = os.getcwd()
ctx = ivy.execute("complex_example_config")

This creates two catalogs, one with intrinsic properties of the galaxies (e.g. position, shape, size) and one with the photometric properties (magnitudes in different bands)

from cosmic_toolbox import arraytools as at
cat_photo = at.load_hdf_cols("ucat_photo.h5")
print(f"parameters of the photometric catalog: {cat_photo.dtype.names}")
cat_int = at.load_hdf("ucat_galaxies.h5")
print(f"parameters of the intrinsic catalog: {cat_int.dtype.names}")
parameters of the photometric catalog: ('abs_mag_g', 'abs_mag_i', 'abs_mag_r', 'abs_mag_y', 'abs_mag_z', 'galaxy_type', 'int_mag_g', 'int_mag_i', 'int_mag_r', 'int_mag_y', 'int_mag_z', 'mag_g', 'mag_i', 'mag_r', 'mag_y', 'mag_z', 'template_coeffs', 'template_coeffs_abs', 'z')
parameters of the intrinsic catalog: ('id', 'x', 'y', 'z', 'template_coeffs', 'template_coeffs_abs', 'abs_mag_lumfun', 'galaxy_type', 'excess_b_v', 'sersic_n', 'int_r50', 'int_e1', 'int_e2', 'gamma1', 'gamma2', 'kappa', 'e1', 'e2', 'r50')

The equivalent GalSBI-SPS configuration starts from the packaged Tortorelli+25 intrinsic configuration. This supplies the current ProMage, surviving-stellar-mass, SSP, filter, and extinction resources. The example then selects the conditional recent-burst SFH, two-population diffuse-dust, and Miller+26 size models, applies the configured shear, and writes both the physical and multi-band photometric catalogues. The default path_shear_map=None gives zero shear; set it to a supported shear map to apply lensing.

complex_example_config_sps.py
import os
from importlib import import_module

base_config = import_module(
    "galsbi.configs.config_Tortorelli+25_intrinsic"
)
for name in [name for name in dir(base_config) if not name.startswith("_")]:
    globals()[name] = getattr(base_config, name)

plugins = [
    "galsbi.ucat_sps.plugins.sample_galaxies_sps",
    "galsbi.ucat.plugins.apply_shear",
    "galsbi.ucat.plugins.write_catalog_photo",
    "galsbi.ucat.plugins.write_catalog",
    "ivy.plugin.show_stats",
]

sfh_population_model = "conditional_snorm_burst_trunc"
dust_attenuation_population_model = "two_population_diffuse_dust"
size_model = "miller2026"

# Omit the two history arrays from the saved catalogue to reduce its size.
retain_sfh_histories = False

filepath_tile = os.path.join(os.getcwd(), "ucat_sps_output")
galaxy_catalog_name = os.path.join(
    filepath_tile, "ucat_sps_galaxies.h5"
)

The three choices are independent. Set sfh_population_model to "tortorelli25_snorm_trunc", "conditional_snorm_trunc", or "conditional_snorm_burst_trunc"; set dust_attenuation_population_model to "tortorelli25" or "two_population_diffuse_dust"; and set size_model to "tortorelli25", "nedkova21_binned", or "miller2026".

Run the configuration and inspect the resulting catalogues with:

ctx_sps = ivy.execute("complex_example_config_sps")

cat_sps_photo = at.load_hdf_cols(
    "ucat_sps_output/ucat_photo.h5"
)
cat_sps_physical = at.load_hdf(
    "ucat_sps_output/ucat_sps_galaxies.h5"
)

print(cat_sps_photo.dtype.names)
print(cat_sps_physical.dtype.names)

Adapting ucat to your workflow

The easiest way to adapt ucat or ucat_sps to your workflow is by using a customized config file. Check out all the different parameters and their description in galsbi.ucat.config.common or checkout GalSBI: Overview of the galaxy population model. Similarly, check out the parameters for the stellar population synthesis version in galsbi.ucat_sps.config.common_sps or GalSBI-SPS: Overview of the galaxy population model. If you require new features, writing a new plugin is straightforward. A template plugin is shown below

new_plugin.py
from ivy.plugin.base_plugin import BasePlugin

class Plugin(BasePlugin):
    def __call__(self):

        # accessing all parameters from the config by calling the context
        par = self.ctx.parameters

        # implement new functionality


    def __str__(self):
        return "new plugin doing something"

If you want to use the generated galaxy catalog to create a simulated image, you can combine your config file with plugins from ufig, for this see the ufig documentation.

To use a galaxy population model that is constrained by data, you can use the galsbi interface. It is possible to use your custom config files within the galsbi module but still using the parameters of one of the galaxy population model, see e.g. Customize configuration.