astrocook.core.system_list module#

astrocook.core.system_list.get_all_w_rest(series_name: str) → List[float][source]#

Returns a list of rest wavelengths in Angstroms for a given series name. Handles single lines, standard multiplets, and custom comma-separated lists.

astrocook.core.system_list.are_overlapping(c1: ComponentDataV2, c2: ComponentDataV2, constraints_map: dict) → bool[source]#

Checks if two components should be grouped together for fitting.

class astrocook.core.system_list.SystemListV2(data: SystemListDataV2)[source]#

Bases: object

API layer for managing component lists, constraints, and fitting.

This class wraps the immutable SystemListDataV2 and provides methods to add, update, delete, and group components. It also initializes the constraint model used by the fitting engine.

Parameters:

data (SystemListDataV2) – The core data container holding the list of components and constraint maps.

__init__(data: SystemListDataV2)[source]#
property components: List[ComponentDataV2]#

List of all component data objects.

property t: Table#

Returns an Astropy Table representation of the system list. Useful for quick inspection or V1 compatibility.

property z: List[float]#

List of redshifts for all components.

property series: List[str]#

List of series names for all components.

property id: List[int]#

List of integer IDs for all components.

property v1_models_t: Any#
property constraint_status: Dict[str, ndarray]#

Dictionary reflecting the free/fixed status of parameters.

property parsed_constraints: Dict[Tuple[int, str], Dict[str, Any]]#
property v2_constraints_for_save: Dict[str, Dict[str, Any]]#
fitting_context(active_uuids: List[str] = None, group_depth: int = 2)[source]#

Context manager for safe fitting.

Temporarily sets the active fitting mask on the constraint model and guarantees cleanup (resetting the mask) even if errors occur.

Parameters:

  • active_uuids (list of str, optional) – List of UUIDs to set as active.

  • group_depth (int, optional) – Grouping depth for finding connected components. Defaults to 2.

to_v1_systlist() → Table | None[source]#

Convert the V2 system list to a V1-compatible Astropy Table.

Used for saving archives in the legacy .acs format.

Returns:

A table containing the system list in V1 format, or None if the list is empty.

Return type:

astropy.table.Table or None

add_components_from_regions(spec: SpectrumV2, region_id_col: str, series_map: Dict[int, str], z_map: Dict[int, float]) → SystemListV2[source]#

Populate the list with initial components based on identified regions.

Parameters:

  • spec (SpectrumV2) – The spectrum containing the region definitions.

  • region_id_col (str) – Name of the column containing region IDs (e.g., 'abs_ids').

  • series_map (dict) – Mapping {region_id: series_name}.

  • z_map (dict) – Mapping {region_id: redshift}.

Returns:

A new instance populated with the identified components.

Return type:

SystemListV2

add_component(series: str, z: float, logN: float = 13.5, b: float = 10.0, btur: float = 0.0) → SystemListV2[source]#

Return a new SystemList with properties of a specific component updated.

Parameters:

  • uuid (str) – The UUID of the component to update.

  • **changes (dict) – Keyword arguments for the fields to change (e.g. z=2.5, logN=14.0).

Returns:

A new instance with the updated component.

Return type:

SystemListV2

get_component_by_uuid(uuid: str) → ComponentDataV2 | None[source]#

Retrieve a component object by its UUID.

Parameters:

uuid (str) – The unique identifier of the component.

Returns:

The component object, or None if not found.

Return type:

ComponentDataV2 or None

update_component(uuid: str, **changes) → SystemListV2[source]#

Return a new SystemList with properties of a specific component updated.

Parameters:

  • uuid (str) – The UUID of the component to update.

  • **changes (dict) – Keyword arguments for the fields to change (e.g. z=2.5, logN=14.0).

Returns:

A new instance with the updated component.

Return type:

SystemListV2

update_components(uuids: List[str], **changes) → SystemListV2[source]#

Batch update parameters for multiple components in a single pass.

This method is significantly faster than calling update_component() repeatedly because it creates a new immutable state only once after applying all changes.

Parameters:

  • uuids (list of str) – A list of component UUIDs to update.

  • **changes (dict) – Keyword arguments specifying the fields to update (e.g., z=2.5). Changes are applied identically to all specified components.

Returns:

A new instance with the components updated.

Return type:

SystemListV2

update_constraint(uuid: str, param: str, is_free: bool | None = None, expression: str | None = None, target_uuid: str | None = None) → SystemListV2[source]#

Update the constraint for a specific component parameter.

Parameters:

  • uuid (str) – The component UUID.

  • param (str) – The parameter name (e.g., 'z', 'logN').

  • is_free (bool, optional) – If True, parameter varies freely. If False, it is fixed or linked.

  • expression (str, optional) – Mathematical string for linking (e.g. "p['target_uuid'].z").

  • target_uuid (str, optional) – UUID of the component this parameter is linked to.

Returns:

A new instance with the updated constraints.

Return type:

SystemListV2

delete_component(uuid: str = None, uuids: list = None) → SystemListV2[source]#

Remove component(s) and clean up constraints linking to them.

Parameters:

  • uuid (str, optional) – Single UUID to delete.

  • uuids (list, optional) – List of UUIDs to delete.

Returns:

A new instance with components removed and constraints cleaned.

Return type:

SystemListV2

get_connected_group(seed_uuids: List[str], max_depth: int = 2) → Set[str][source]#

Find a set of components that must be fitted together.

This method traverses relationships to find all “fluid neighbors” of the seed components (via links, spectral overlap, or kinematic proximity).

Parameters:

  • seed_uuids (list of str) – The UUIDs of the components initially selected for fitting.

  • max_depth (int, optional) – How many degrees of separation to traverse. Defaults to 2.

Returns:

The full set of UUIDs in the connected group.

Return type:

set of str

merge(other: SystemListV2, copy_uuids: bool = False) → SystemListV2[source]#

Merge components from another system list into this one.

Parameters:

  • other (SystemListV2) – The source list to copy from.

  • copy_uuids (bool, optional) – If True, keeps original UUIDs (risky if merging into self). If False, regenerates UUIDs to avoid conflicts. Defaults to False.

Returns:

A new merged system list.

Return type:

SystemListV2

optimize_hierarchy(spec: SpectrumV2, uuid_seed: str, max_components: int = 5, threshold_sigma: float = 2.5, aic_penalty: float = 0.0, z_window_kms: float = 100.0, min_dv: float = 10.0, group_depth: int = 2, patience: int = 2) → SystemListV2[source]#

Iteratively adds components to a system to minimize residuals using the Akaike Information Criterion (AIC).

This method performs the following steps:

  1. Baseline Fit: Fits the seed component (and its connected group) to establish a baseline AIC.

  2. Residual Scan: Calculates the residuals (Flux - Model) over the specified velocity window.

  3. Candidate Detection: Identifies the strongest un-modeled absorption feature (negative residual).

  4. Trial: If the feature exceeds threshold_sigma, adds a new component at that position.

  5. Evaluation: Fits the new configuration. If AIC improves (decreases) by aic_penalty, the new component is kept.

  6. Termination: Repeats until max_components is reached or patience is exhausted.

Parameters:

  • spec (SpectrumV2) – The spectrum data used for fitting and residual calculation.

  • uuid_seed (str) – UUID of the seed component. This defines the series (e.g. CIV) and the center of the velocity search window.

  • max_components (int, optional) – Maximum number of additional components to attempt adding (default: 5).

  • threshold_sigma (float, optional) – Significance level (in standard deviations) of the residual dip required to trigger a new component trial (default: 2.5).

  • aic_penalty (float, optional) – Minimum AIC improvement required to accept a new component (default: 0.0). Higher values favor simpler models (Occam’s razor).

  • z_window_kms (float, optional) – The velocity window size (km/s) around the seed component to search for residuals (default: 100.0).

  • min_dv (float, optional) – Minimum velocity separation (km/s) required between a candidate and existing components. Lower this to de-blend close doublets (default: 10.0).

  • group_depth (int, optional) – Depth for finding connected neighbors during the fit (default: 2).

  • patience (int, optional) – Number of consecutive trials allowed without AIC improvement before stopping (default: 2).

Returns:

A new system list containing the optimized components.

Return type:

SystemListV2

remove_in_region(obs_min: Quantity, obs_max: Quantity) → SystemListV2[source]#

Remove components whose center falls within the observed wavelength range.

Parameters:

  • obs_min (Quantity) – The wavelength bounds.

  • obs_max (Quantity) – The wavelength bounds.

Returns:

A new instance with components removed.

Return type:

SystemListV2

filter_by_criteria(condition_func) → SystemListV2[source]#

Remove components whose center falls within the observed wavelength range.

Parameters:

  • obs_min (Quantity) – The wavelength bounds.

  • obs_max (Quantity) – The wavelength bounds.

Returns:

A new instance with components removed.

Return type:

SystemListV2

filter_by_range(xmin_nm: float, xmax_nm: float) → SystemListV2[source]#

Return a new SystemListV2 containing only components within the range.

Parameters:

  • xmin_nm (float) – Wavelength range in nanometers.

  • xmax_nm (float) – Wavelength range in nanometers.

Returns:

A new instance with filtered components.

Return type:

SystemListV2