astrocook.core.structures module#

class astrocook.core.structures.SessionMetadataV2(constraints_by_uuid: ~typing.Dict[str, ~typing.Dict[str, ~typing.Any]] = <factory>, v1_reconstruction_data: ~typing.Any = None, log_history_json: ~typing.Any = <factory>, log_type: str = 'v1_legacy', component_uuids: ~typing.List[str] = <factory>)[source]#

Bases: object

Core immutable structure for holding constraints, configuration, and history.

This structure is designed to be serialized to a JSON or YAML file within the .acs archive. It separates the lightweight metadata from the heavy spectral arrays.

Parameters:

  • constraints_by_uuid (dict) – A mapping of Component UUIDs to constraint dictionaries.

  • v1_reconstruction_data (Any) – Legacy data structure preserved for technical debt logging or V1 reconstruction.

  • log_history_json (Any) – The serialized log object (either a V2 dict or V1 JSON format).

  • log_type (str) – Type of log stored: 'v2', 'v1_artifact', or 'v1_legacy'. Defaults to 'v1_legacy'.

  • component_uuids (list of str) – An ordered list of all component UUIDs in the session.

constraints_by_uuid: Dict[str, Dict[str, Any]]#
v1_reconstruction_data: Any = None#
log_history_json: Any#
log_type: str = 'v1_legacy'#
component_uuids: List[str]#
__init__(constraints_by_uuid: ~typing.Dict[str, ~typing.Dict[str, ~typing.Any]] = <factory>, v1_reconstruction_data: ~typing.Any = None, log_history_json: ~typing.Any = <factory>, log_type: str = 'v1_legacy', component_uuids: ~typing.List[str] = <factory>) → None#
class astrocook.core.structures.DataColumnV2(values: ndarray, unit: Unit, description: str = '')[source]#

Bases: object

Immutable container for a single column of data with physical units.

Parameters:

  • values (np.ndarray) – The numerical data array.

  • unit (astropy.units.Unit) – The physical unit associated with the values.

  • description (str, optional) – A short description of the column’s content.

values: ndarray#
unit: Unit#
description: str = ''#
property quantity: Quantity#

Return the column data as an Astropy Quantity.

Combines the numerical values and the physical unit.

property value: ndarray#

Return the raw numerical array.

Alias for .values to support legacy/Astropy-style access.

__init__(values: ndarray, unit: Unit, description: str = '') → None#
class astrocook.core.structures.SpectrumDataV2(x: ~astrocook.core.structures.DataColumnV2, xmin: ~astrocook.core.structures.DataColumnV2, xmax: ~astrocook.core.structures.DataColumnV2, y: ~astrocook.core.structures.DataColumnV2, dy: ~astrocook.core.structures.DataColumnV2, aux_cols: ~typing.Dict[str, ~astrocook.core.structures.DataColumnV2] = <factory>, meta: ~typing.Dict[str, ~typing.Any] = <factory>, z_em: float = 0.0, resol: float = 0.0)[source]#

Bases: object

Immutable core container for all spectral data.

This class holds the “heavy” numerical arrays (flux, wavelength, error) and auxiliary columns. It is the data payload for SpectrumV2.

Parameters:

  • x (DataColumnV2) – The independent variable (wavelength or velocity).

  • xmin (DataColumnV2) – Lower bound of the x-bins.

  • xmax (DataColumnV2) – Upper bound of the x-bins.

  • y (DataColumnV2) – The dependent variable (flux density).

  • dy (DataColumnV2) – The 1-sigma uncertainty on y.

  • aux_cols (dict of DataColumnV2) – Additional columns (e.g. 'cont', 'model', 'abs_mask').

  • meta (dict) – Header keywords and other metadata.

  • z_em (float) – Emission redshift of the target object.

  • resol (float) – Median resolving power \(R = \lambda / \Delta\lambda\).

x: DataColumnV2#
xmin: DataColumnV2#
xmax: DataColumnV2#
y: DataColumnV2#
dy: DataColumnV2#
aux_cols: Dict[str, DataColumnV2]#
meta: Dict[str, Any]#
z_em: float = 0.0#
resol: float = 0.0#
classmethod from_flat_data(x_values: ndarray, x_unit: Unit, y_values: ndarray, y_unit: Unit, dy_values: ndarray, xmin_values: ndarray | None = None, xmax_values: ndarray | None = None, aux_data: Dict[str, tuple] | None = None, meta: Dict[str, Any] | None = None, z_em: float = 0.0, resol: float = 0.0) → SpectrumDataV2[source]#

Factory method to create a SpectrumDataV2 from raw NumPy arrays.

Parameters:

  • x_values (np.ndarray) – Wavelength/Velocity data.

  • x_unit (astropy.units.Unit) – Unit for the x-axis.

  • y_values (np.ndarray) – Flux data.

  • y_unit (astropy.units.Unit) – Unit for the y-axis (and dy).

  • dy_values (np.ndarray) – Error data.

  • xmin_values (np.ndarray, optional) – Lower bin edges. Defaults to x_values if None.

  • xmax_values (np.ndarray, optional) – Upper bin edges. Defaults to x_values if None.

  • aux_data (dict, optional) – Dictionary of auxiliary columns: {'name': (values, unit, description)}.

  • meta (dict, optional) – Metadata dictionary.

  • z_em (float, optional) – Emission redshift. Defaults to 0.0.

Returns:

The initialized data object.

Return type:

SpectrumDataV2

__init__(x: ~astrocook.core.structures.DataColumnV2, xmin: ~astrocook.core.structures.DataColumnV2, xmax: ~astrocook.core.structures.DataColumnV2, y: ~astrocook.core.structures.DataColumnV2, dy: ~astrocook.core.structures.DataColumnV2, aux_cols: ~typing.Dict[str, ~astrocook.core.structures.DataColumnV2] = <factory>, meta: ~typing.Dict[str, ~typing.Any] = <factory>, z_em: float = 0.0, resol: float = 0.0) → None#
class astrocook.core.structures.ComponentDataV2(id: int, z: float, dz: float | None, logN: float, dlogN: float | None, b: float, db: float | None, btur: float = 0.0, dbtur: float | None = None, func: str = 'voigt', series: str = 'Ly_a', chi2: float | None = None, resol: float | None = None, uuid: str = <factory>)[source]#

Bases: object

Immutable data structure for a single absorption component (Voigt profile).

id: int#

Internal integer ID (from V1 legacy logic).

z: float#

Redshift of the component center

dz: float | None#

Uncertainty on redshift.

logN: float#

Logarithmic column density (cm^-2).

dlogN: float | None#

Uncertainty on logN.

b: float#

Doppler broadening parameter (km/s).

db: float | None#

Uncertainty on b.

btur: float = 0.0#

Turbulent broadening contribution (km/s).

dbtur: float | None = None#

Uncertainty on btur.

func: str = 'voigt'#

'voigt').

Type:

Profile function name (default

series: str = 'Ly_a'#

Atomic series name (e.g., 'Ly_a', 'CIV').

chi2: float | None = None#

Reduced Chi-Squared of the fit group this component belongs to.

resol: float | None = None#

Resolution used for the fit.

uuid: str#

A globally unique, stable identifier for V2 constraints and linking.

__init__(id: int, z: float, dz: float | None, logN: float, dlogN: float | None, b: float, db: float | None, btur: float = 0.0, dbtur: float | None = None, func: str = 'voigt', series: str = 'Ly_a', chi2: float | None = None, resol: float | None = None, uuid: str = <factory>) → None#
class astrocook.core.structures.ParameterConstraintV2(is_free: bool, target_uuid: str | None = None, expression: str | None = None, v1_target_id: int | None = None)[source]#

Bases: object

Immutable structure defining a constraint for a single parameter.

Used by the fitting engine to determine if a parameter is free, fixed, or linked to another component.

is_free: bool#

If True, the parameter varies during minimization.

target_uuid: str | None = None#

If set, this parameter is linked to the component with this UUID.

expression: str | None = None#

A mathematical string expression for linking (e.g. "p['{uuid}'].z").

v1_target_id: int | None = None#

Legacy ID of the target component (for debugging/reconstruction only).

__init__(is_free: bool, target_uuid: str | None = None, expression: str | None = None, v1_target_id: int | None = None) → None#
class astrocook.core.structures.SystemListDataV2(components: ~typing.List[~astrocook.core.structures.ComponentDataV2] = <factory>, v1_header_constraints: ~typing.Dict[str, ~typing.Any] = <factory>, parsed_constraints: ~typing.Dict[~typing.Tuple[str, str], ~astrocook.core.structures.ParameterConstraintV2] = <factory>, v2_constraints_map: ~typing.Dict[str, ~typing.Dict[str, ~astrocook.core.structures.ParameterConstraintV2]] = <factory>, v1_id_to_uuid_map: ~typing.Dict[int, str] = <factory>, v1_models_t: ~typing.Any = None, meta: ~typing.Dict[str, ~typing.Any] = <factory>)[source]#

Bases: object

Immutable container for system components and constraints.

This class replaces the mutable tables used in V1. It holds the list of components and the maps defining their relationships.

components: List[ComponentDataV2]#

The list of absorption components.

v1_header_constraints: Dict[str, Any]#

Legacy constraints from V1 file headers.

__init__(components: ~typing.List[~astrocook.core.structures.ComponentDataV2] = <factory>, v1_header_constraints: ~typing.Dict[str, ~typing.Any] = <factory>, parsed_constraints: ~typing.Dict[~typing.Tuple[str, str], ~astrocook.core.structures.ParameterConstraintV2] = <factory>, v2_constraints_map: ~typing.Dict[str, ~typing.Dict[str, ~astrocook.core.structures.ParameterConstraintV2]] = <factory>, v1_id_to_uuid_map: ~typing.Dict[int, str] = <factory>, v1_models_t: ~typing.Any = None, meta: ~typing.Dict[str, ~typing.Any] = <factory>) → None#
parsed_constraints: Dict[Tuple[str, str], ParameterConstraintV2]#

Map of (Component UUID, Parameter Name) -> ConstraintDataV2.

v2_constraints_map: Dict[str, Dict[str, ParameterConstraintV2]]#

Constraint}}.

Type:

Nested map {UUID

Type:

{ParamName

v1_id_to_uuid_map: Dict[int, str]#

Map of integer IDs to V2 UUIDs.

v1_models_t: Any = None#
meta: Dict[str, Any]#

Metadata for the system list.

class astrocook.core.structures.LogEntryV2(recipe_name: str, params: Dict[str, Any])[source]#

Bases: object

A single entry in the V2 analysis log.

Corresponds 1-to-1 with a state change in the Session history.

__init__(recipe_name: str, params: Dict[str, Any]) → None#
recipe_name: str#
params: Dict[str, Any]#
class astrocook.core.structures.HistoryLogV2[source]#

Bases: object

Manages the linear history of operations (Log V2).

This class maintains a list of LogEntryV2 objects matching the stack of immutable states in the session manager. It supports truncation to handle branching history (undo/redo logic).

entries#

The list of operations performed.

Type:

list of LogEntryV2

current_index#

Pointer to the currently active log entry (state).

Type:

int

__init__()[source]#
property is_v2_log: bool#

Return True, indicating this is a V2-native log structure.

add_entry(recipe_name: str, params: Dict[str, Any])[source]#

Add a new log entry, truncating any ‘future’ history (from Undo actions).

Parameters:

  • recipe_name (str) – The name of the recipe executed.

  • params (dict) – The parameters used for the recipe.

undo() → bool[source]#

Add a new log entry, truncating any ‘future’ history (from Undo actions).

Parameters:

  • recipe_name (str) – The name of the recipe executed.

  • params (dict) – The parameters used for the recipe.

redo() → bool[source]#

Move the history pointer forward one step.

Returns:

True if redo was successful, False if already at the latest entry.

Return type:

bool

class astrocook.core.structures.V1LogArtifact(v1_log_json: dict)[source]#

Bases: object

A read-only wrapper for legacy V1 logs.

Used to display the history of a session loaded from a V1 archive without converting it to the full V2 structure.

Parameters:

v1_log_json (dict) – The raw JSON dictionary from the V1 archive.

__init__(v1_log_json: dict)[source]#
property is_v2_log: bool#

Return False, indicating this is a legacy V1 log wrapper.

On this page

This Page