sheap.SheapModelBuilder.SheapModelBuilder module

SheapModelBuilder

Builds spectral fitting regions from wavelength bounds and YAML templates. It assembles narrow/broad/outflow/wind/BAL/FeII components, adds continuum (and optional Balmer continua), and generates parameter‑tying rules suitable for downstream fitting.

Main features

  • Load line definitions from YAML repositories within a wavelength window.

  • Instantiate SpectralLine objects for narrow/broad/outflow/wind/BAL/FeII.

  • Add continuum components (power law, linear; Balmer/Balmer high order optional).

  • Group lines into SPAF composites and apply known/amplitude ties.

  • Produce a SheapModel and a fitting routine configuration.

param xmin:

Lower wavelength bound of the region (Å).

type xmin:

float

param xmax:

Upper wavelength bound of the region (Å).

type xmax:

float

param n_narrow:

Number of narrow components per line (default: 1).

type n_narrow:

int, optional

param n_broad:

Number of broad components per line (default: 1).

type n_broad:

int, optional

param line_repository_path:

Paths to YAML files defining line templates. If not provided, loads all templates in SuportData/LineRepository.

type line_repository_path:

list[str | pathlib.Path], optional

param fe_mode:

How to include FeII emission (default: “template”).

type fe_mode:

{“template”, “model”, “none”}, optional

param continuum_profile:

Continuum profile name (keys of PROFILE_CONTINUUM_FUNC_MAP; default: “powerlaw”).

type continuum_profile:

str, optional

param group_method:

If True, group lines and apply default ties automatically (default: True).

type group_method:

bool, optional

param add_outflow:

Include outflow components for selected narrow lines (default: False).

type add_outflow:

bool, optional

param add_winds:

Include wind components for selected broad lines (default: False).

type add_winds:

bool, optional

param add_balmer_continuum:

Include Balmer continuum component (default: False).

type add_balmer_continuum:

bool, optional

param add_balmerhighorder_continuum:

Include Balmer high‑order continuum template (default: False).

type add_balmerhighorder_continuum:

bool, optional

param add_uncommon_narrow:

Include lines marked as uncommon (default: False).

type add_uncommon_narrow:

bool, optional

param add_host_miles:

Include a host‑galaxy template from MILES (True for defaults or a dict of kwargs).

type add_host_miles:

bool | dict, optional

param tied_narrow_to:

Main line (or per‑component map) to which narrow lines are tied.

type tied_narrow_to:

str | dict, optional

param tied_broad_to:

Main line (or per‑component map) to which broad lines are tied.

type tied_broad_to:

str | dict, optional

param n_max_component_outflow:

Max outflow components per line (default: 1).

type n_max_component_outflow:

int, optional

param n_max_component_winds:

Max wind components per line (default: 1).

type n_max_component_winds:

int, optional

param n_max_component_bal:

Max BAL components per line (default: 1).

type n_max_component_bal:

int, optional

param verbose:

Print informational messages (default: True).

type verbose:

bool, optional

lines_available

Loaded line definitions keyed by YAML stem.

Type:

dict[str, list[dict]]

pseudo_region_available

Available pseudo‑region keys found in YAML.

Type:

list[str]

sheapmodel

Final container with all built SpectralLine objects.

Type:

SheapModel

known_tied_relations

Default amplitude/center ties used during grouping when enabled.

Type:

list[tuple]

Examples

>>> cb = SheapModelBuilder(6500, 6600, n_narrow=2, n_broad=1, add_outflow=True)
>>> cb.make_region()
>>> config = cb._make_fitting_routine(
...     list_num_steps=[2000, 2000],
...     list_learning_rate=[1e-1, 1e-2]
... )

Notes

  • If the wavelength span is shorter than LINEAR_RANGE_THRESHOLD, the continuum is forced to linear for stability.

  • group_method=True collapses lines into SPAF composites per region/element and applies known ties (e.g., [O III], [N II]) automatically.

  • FeII “template” mode inserts broad templates spanning the requested range; “model” loads individual FeII lines; “none” skips FeII.

class SheapModelBuilder(xmin, xmax, n_narrow=1, n_broad=1, line_repository_path=None, fe_mode='template', continuum_profile='powerlaw', group_method=True, add_outflow=False, add_winds=False, add_balmer_continuum=False, add_uncommon_narrow=False, add_BAL=False, add_balmerhighorder_continuum=False, add_host_miles=None, tied_narrow_to=None, tied_broad_to=None, n_max_component_outflow=1, n_max_component_winds=1, n_max_component_bal=1, **kwargs)[source]

Bases: object

Builds spectral fitting regions given wavelength bounds and YAML templates, including narrow, broad, outflow, and FeII components, plus parameter tying.

Parameters:

  • xmin (float) – Lower wavelength bound of the region (Å).

  • xmax (float) – Upper wavelength bound of the region (Å).

  • n_narrow (int, optional) – Number of narrow components per line, by default 1.

  • n_broad (int, optional) – Number of broad components per line, by default 1.

  • line_repository_path (list of str or Path, optional) – Paths to YAML files defining line templates. Defaults to all in LineRepository/.

  • fe_mode ({'template', 'model', 'none'}, optional) – Mode for FeII components, by default “template”.

  • continuum_profile (str, optional) – Continuum profile name (must be in PROFILE_CONTINUUM_FUNC_MAP), by default “powerlaw”.

  • group_method (bool, optional) – Whether to apply automatic grouping and tying of parameters, by default True.

  • add_outflow (bool, optional) – Include outflow components for narrow lines, by default False.

  • add_winds (bool, optional) – Include wind components for broad lines, by default False.

  • add_balmer_continuum (bool, optional) – Include Balmer continuum component, by default False.

  • add_balmerhighorder_continuum (bool, optional) – Include Balmer high order continuum component, by default False.

  • add_uncommon_narrow (bool, optional) – Include uncommon narrow lines, by default False.

  • add_host_miles (bool or dict, optional) – Include host‐galaxy template from MILES; if dict, passes its keys to the builder.

  • verbose (bool, optional) – Print informational messages during building, by default True.

  • tied_narrow_to (Optional[Union[str, Dict[int, Dict[str, int]]]])

  • tied_broad_to (Optional[Union[str, Dict[int, Dict[str, int]]]])

lines_available

Loaded line definitions from YAML.

Type:

dict[str, list of dict]

pseudo_region_available

Keys of available pseudo‑regions from YAML.

Type:

list[str]

sheapmodel

Container of all SpectralLine objects after building.

Type:

SheapModel

tied_relations

Parameter‐tying specifications used in fitting routine.

Type:

list

Examples

>>> rb = SheapModelBuilder(6500, 6600, n_narrow=2, n_broad=1, add_outflow=True)
>>> rb.make_region()
>>> routine = rb._make_fitting_routine(list_num_steps=[2000,2000], list_learning_rate=[1e-1,1e-2])
lines_prone_outflow = ['CII]', '[NeV]a', '[NeV]b', 'OIIIc', 'OIIIb', 'NeIIIa', 'OIIb', 'OIIa', '[NeIV]', '[OII]', '[NeIII]']
lines_prone_winds = ['Lyalpha', 'CIV', 'AlIII', 'MgII', 'Halpha', 'Hbeta']
lines_prone_bal = ['CIV', 'AlIII', 'MgII', 'NV', 'SiIV', 'OIV]', ' OVIa', ' OVIb']
available_fe_modes = ['template', 'model', 'none']
available_continuum_profiles = ['linear', 'powerlaw', 'brokenpowerlaw', 'logparabola', 'exp_cutoff', 'polynomial', 'none']
LINEAR_RANGE_THRESHOLD = 1000
known_tied_relations: List[Tuple[Tuple[str, ...], List[str]]] = [(('OIIIb', 'OIIIc'), ['amplitude_OIIIb_component_narrow', 'amplitude_OIIIc_component_narrow', '*0.3']), (('NIIa', 'NIIb'), ['amplitude_NIIa_component_narrow', 'amplitude_NIIb_component_narrow', '*0.3']), (('NIIa', 'NIIb'), ['center_NIIa_component_narrow', 'center_NIIb_component_narrow']), (('OIIIb', 'OIIIc'), ['center_OIIIb_component_narrow', 'center_OIIIc_component_narrow'])]
make_region(xmin=None, xmax=None, n_broad=None, n_narrow=None, fe_mode=None, continuum_profile=None, group_method=None, add_outflow=None, add_winds=None, add_balmer_continuum=None, add_uncommon_narrow=None, add_host_miles=None, tied_broad_to=None, tied_narrow_to=None, add_BAL=None, add_balmerhighorder_continuum=None)[source]

Build a SheapModel of SpectralLine objects based on settings.

Parameters:

  • xmin (float, optional) – Override for lower wavelength bound.

  • xmax (float, optional) – Override for upper wavelength bound.

  • n_broad (int, optional) – Override for broad-line count.

  • n_narrow (int, optional) – Override for narrow-line count.

  • fe_mode (str, optional) – Override for FeII mode.

  • continuum_profile (str, optional) – Override for continuum profile.

  • group_method (bool, optional) – Override for grouping behavior.

  • add_outflow (bool, optional) – Override for outflow inclusion.

  • add_winds (bool, optional) – Override for wind inclusion.

  • add_balmer_continuum (bool, optional) – Override for Balmer continuum.

  • add_uncommon_narrow (bool, optional) – Override for uncommon narrow-line inclusion.

  • add_host_miles (bool or dict, optional) – Override for host-galaxy options.