Transitioning from v0.5.0-beta to future versions (AKA: translating to EmissionModels)

[WillJRoper]

Once #624 is merged, any code that uses get_spectra_incident, get_spectra_reprocessed, get_lines_intrinsic etc. (i.e any get_spectra_* or get_lines_* generator, including the particle equivalents) will fail.

This is due to the pivot in workflow from specific generator methods to more generalised methods combined with EmissionModels (see below for more details).

In short, if you don't want to modify your pipelines, ensure you are installing version v0.5.0-beta, this tag will forever remain compatible with the old generator methods.

To convert your codes to use the new workflow you need to create EmissionModels that describe the different spectra you want to generate and how they relate to each other. This enables the construction of complex spectra on multiple different components with a single call to get_spectra (or the same for get_lines and their per particle equivalents).

It is possible to construct your own EmissionModels and make any combination of spectra you like but for simplicity of use we have implemented a whole host of commonly used models which can be imported and used "out of the box". More details on all of this will be available in the emission models docs when #624 is merged.

To give you an idea of what the translation might entail here is a comparison of the two methods for getting spectra. These methods are equivalent. The emission model version combines premade models together using a hybrid of self-defined models and pre-made models.

Old method

def get_spectra_traditional(gals, grid):
    """
    Get the spectra for a galaxy.

    This function uses the "traditional" method of calculating the spectra
    for individual galaxies using methods on a component.

    Args:
        gals (list)
            A list of galaxy objects.
        grid (Grid)
            The grid object to use for the emission model.
        filters (FilterCollection)
            The filter collection object to use.
        age_pivot (unyt_quantity)
            The age to pivot the spectra at for the traditional method.
    """
    for gal in gals:
        spec = {}

        # Get pure stellar spectra
        old_spec = gal.stars.get_spectra_incident(grid, old=age_pivot)

        # Get nebular spectra for each star particle
        young_reprocessed_spec = gal.stars.get_spectra_reprocessed(
            grid, young=age_pivot
        )

        # Save intrinsic stellar spectra
        spec["intrinsic"] = young_reprocessed_spec + old_spec

        # Simple screen model
        spec["screen"] = spec["intrinsic"].apply_attenuation(
            dust_curve=PowerLaw(slope=-1), tau_v=0.33
        )

New method

from synthesizer.emission_models import (
    EmissionModel,
    IncidentEmission,
    ReprocessedEmission,
)

def get_spectra_emission_model(gals, grid):
    """
    Get the spectra for a galaxy using an emission model.

    Args:
        gals (list)
            A list of galaxy objects.
        grid (Grid)
            The grid object to use for the emission model.
    """
    # Define the old incident model
    old_incident = IncidentEmission(
        grid=grid,
        label="old_incident",
        mask_attr="ages",
        mask_thresh=10.0 * Myr,
        mask_op=">",
    )

    # Define the young reprocessed model
    young_reprocessed = ReprocessedEmission(
        grid=grid,
        label="young_reprocessed",
        mask_attr="ages",
        mask_thresh=10.0 * Myr,
        mask_op="<=",
    )

    # Define the intrinsic model
    intrinsic = EmissionModel(
        label="intrinsic",
        combine=[old_incident, young_reprocessed],
        emitter="stellar",
    )

    # Define the screen model
    screen = EmissionModel(
        grid=grid,
        label="screen",
        apply_dust_to=intrinsic,
        dust_curve=PowerLaw(slope=-1),
        tau_v=0.33,
        emitter="stellar",
    )

    for gal in gals:
        gal.stars.get_spectra(screen)

This approach gives the user a lot more control over the spectra they can create while simplifying the creation of complex spectra.

Note that something like the Pacman or Charlot & Fall models can be imported and used directly. You aren't tied to defining each step in constructing a model yourself as shown above. This is also true for a bunch of other premade spectra within the emission_models module.

from synthesizer.emission_models import CharlotFall2000

cf_model = CharlotFall2000(
    grid,
    tau_v_ism=0.33,
    tau_v_nebular=0.67,
    dust_curve_ism=PowerLaw(slope=-0.7),
    dust_curve_nebular=PowerLaw(slope=-1.3),
    age_pivot=10 * dimensionless,
)
spec = gal.stars.get_spectra(cf_model)

Note that there's an importable list of currently implemented premade models:

from synthesizer.emission_models import PREMADE_MODELS
print(PREMADE_MODELS)

[
    'AttenuatedEmission', 
    'DustEmission', 
    'IncidentEmission', 
    'LineContinuumEmission', 
    'TransmittedEmission', 
    'EscapedEmission', 
    'NebularContinuumEmission', 
    'NebularEmission', 
    'ReprocessedEmission', 
    'EmergentEmission', 
    'TotalEmission', 
    'CharlotFall2000', 
    'PacmanEmission', 
    'BimodalPacmanEmission', 
    'Template', 
    'NLRIncidentEmission', 
    'BLRIncidentEmission', 
    'NLRTransmittedEmission', 
    'BLRTransmittedEmission', 
    'DiscIncidentEmission', 
    'DiscTransmittedEmission', 
    'DiscEscapedEmission', 
    'DiscEmission', 
    'TorusEmission', 
    'AGNIntrinsicEmission', 
    'UnifiedAGN',
]

Please feel free to ask any question here!