Reference Data

reference_data

Módulo de datos de referencia para análisis XPS.

Este módulo contiene las clases y funciones para manejar datos de referencia de elementos químicos, incluyendo energías de enlace, desplazamientos químicos y información de compuestos para identificación automática.

Classes

CompoundReference

Bases: XPSBaseModel

Datos de referencia para un compuesto específico.

Attributes

orbital : str Orbital asociado (ej: "1s", "2p") binding_energy_range : tuple of float Energía o rango de energías de enlace (min, max) en eV peak_position : float, optional Posición del pico principal en eV chemical_shift : float, optional Desplazamiento químico respecto al elemento puro en eV

ElementReference

Bases: XPSBaseModel

Base de datos completa de un elemento químico.

Attributes

symbol : str Símbolo del elemento (ej: "Li", "C", "O") element : str Nombre completo del elemento atomic_number : int Número atómico photoelectron_lines : list[PhotoelectronLine] Lista con las líneas fotoeléctronicas por orbital compounds : dict[str, CompoundReference] Diccionario de compuestos de referencia binding_energy_most_useful : float, optional Energía de enlace más útil en eV spin_orbital_splitting : float, optional Separación spin-orbital en eV

Methods:

get_main_line

get_main_line() -> PhotoelectronLine

Obtiene la línea fotoeléctrica principal (mayor intensidad).

Returns

PhotoelectronLine Línea con mayor intensidad relativa

Raises

ValueError Si no hay líneas disponibles para el elemento

Source code in src/xps_analyzer/reference_data/elements.py

def get_main_line(self) -> PhotoelectronLine:
    """
    Obtiene la línea fotoeléctrica principal (mayor intensidad).

    Returns
    -------
    PhotoelectronLine
        Línea con mayor intensidad relativa

    Raises
    ------
    ValueError
        Si no hay líneas disponibles para el elemento
    """
    if not self.photoelectron_lines:
        raise ValueError(
            f"No hay líneas fotoelectrónicas disponibles para {self.symbol}"
        )

    # Si existe binding_energy_most_useful, buscar la línea correspondiente
    if self.binding_energy_most_useful is not None:
        for line in self.photoelectron_lines:
            if (
                line.binding_energy is not None
                and abs(line.binding_energy - self.binding_energy_most_useful) < 0.1
            ):
                return line

    # Fallback: retornar la primera línea disponible
    return self.photoelectron_lines[0]

get_compound

get_compound(name: str) -> CompoundReference | None

Busca un compuesto por nombre.

Parameters

name : str Nombre del compuesto a buscar

Returns

CompoundReference or None Referencia del compuesto si se encuentra

Source code in src/xps_analyzer/reference_data/elements.py

def get_compound(self, name: str) -> CompoundReference | None:
    """
    Busca un compuesto por nombre.

    Parameters
    ----------
    name : str
        Nombre del compuesto a buscar

    Returns
    -------
    CompoundReference or None
        Referencia del compuesto si se encuentra
    """
    return self.compounds.get(name)

PhotoelectronLine

Bases: XPSBaseModel

Representa una línea fotoeléctrica de un orbital específico.

Attributes

line : str Designación de la línea (ej: "1s", "2p1/2", "2p3/2", "KLL") binding_energy : float Energía de enlace en eV x_ray_source : str, optional Fuente de rayos X utilizada (ej: "Mg_Ka", "Al_Ka") type : str, default="core" Tipo de línea ("core" o "Auger") kinetic_energy : float, optional Energía cinética en eV (solo para líneas Auger)

ReferenceDatabase

Bases: XPSBaseModel

Base de datos completa de elementos de referencia.

Attributes

elements : dict Diccionario con elementos indexados por símbolo version : str Versión de la base de datos source : str Fuente de los datos de referencia

Methods:

get_element

get_element(symbol: str) -> ElementReference | None

Obtiene datos de un elemento por símbolo.

Parameters

symbol : str Símbolo del elemento

Returns

ElementReference or None Referencia del elemento si existe

Source code in src/xps_analyzer/reference_data/elements.py

def get_element(self, symbol: str) -> ElementReference | None:
    """
    Obtiene datos de un elemento por símbolo.

    Parameters
    ----------
    symbol : str
        Símbolo del elemento

    Returns
    -------
    ElementReference or None
        Referencia del elemento si existe
    """
    return self.elements.get(symbol.upper())

search_by_binding_energy

search_by_binding_energy(
    energy: float, tolerance: float = 2.0
) -> list[tuple[str, str]]

Busca elementos/compuestos por energía de enlace.

Parameters

energy : float Energía de enlace a buscar (eV) tolerance : float, default=2.0 Tolerancia de búsqueda (eV)

Returns

List[Tuple[str, str]] Lista de tuplas (elemento, orbital/compuesto)

Source code in src/xps_analyzer/reference_data/elements.py

def search_by_binding_energy(
    self, energy: float, tolerance: float = 2.0
) -> list[tuple[str, str]]:
    """
    Busca elementos/compuestos por energía de enlace.

    Parameters
    ----------
    energy : float
        Energía de enlace a buscar (eV)
    tolerance : float, default=2.0
        Tolerancia de búsqueda (eV)

    Returns
    -------
    List[Tuple[str, str]]
        Lista de tuplas (elemento, orbital/compuesto)
    """
    matches = []
    for element in self.elements.values():
        # Buscar en líneas fotoeléctronicas
        for line in element.photoelectron_lines:
            if (
                line.binding_energy is not None
                and abs(line.binding_energy - energy) <= tolerance
            ):
                matches.append((element.symbol, line.line))

        # Buscar en compuestos
        for compound_name, compound in element.compounds.items():
            # Solo buscar si peak_position está definido
            if compound.peak_position is not None:
                if abs(compound.peak_position - energy) <= tolerance:
                    matches.append((element.symbol, compound_name))

    return matches

get_chemical_shifts

get_chemical_shifts(element_symbol: str) -> dict[str, float]

Obtiene todos los desplazamientos químicos de un elemento.

Parameters

element_symbol : str Símbolo del elemento

Returns

Dict[str, float] Diccionario con compuesto -> desplazamiento químico

Source code in src/xps_analyzer/reference_data/elements.py

def get_chemical_shifts(self, element_symbol: str) -> dict[str, float]:
    """
    Obtiene todos los desplazamientos químicos de un elemento.

    Parameters
    ----------
    element_symbol : str
        Símbolo del elemento

    Returns
    -------
    Dict[str, float]
        Diccionario con compuesto -> desplazamiento químico
    """
    element = self.get_element(element_symbol)
    if not element:
        return {}

    # Filtrar solo compuestos con chemical_shift definido
    return {
        comp_name: comp.chemical_shift
        for comp_name, comp in element.compounds.items()
        if comp.chemical_shift is not None
    }

list_elements

list_elements() -> list[str]

Lista todos los elementos disponibles.

Returns

List[str] Lista de símbolos de elementos

Source code in src/xps_analyzer/reference_data/elements.py

def list_elements(self) -> list[str]:
    """
    Lista todos los elementos disponibles.

    Returns
    -------
    List[str]
        Lista de símbolos de elementos
    """
    return list(self.elements.keys())

Functions:

load_reference_database

load_reference_database(data_path: Path | None = None) -> ReferenceDatabase

Carga la base de datos de referencia desde archivo JSON.

Parameters

data_path : Path, optional Ruta al archivo de datos JSON. Si None, usa ubicación por defecto.

Returns

ReferenceDatabase Base de datos cargada

Source code in src/xps_analyzer/reference_data/elements.py

def load_reference_database(data_path: Path | None = None) -> ReferenceDatabase:
    """
    Carga la base de datos de referencia desde archivo JSON.

    Parameters
    ----------
    data_path : Path, optional
        Ruta al archivo de datos JSON. Si None, usa ubicación por defecto.

    Returns
    -------
    ReferenceDatabase
        Base de datos cargada
    """

    global _reference_db_cache

    # Verificar caché
    if _reference_db_cache is not None:
        return _reference_db_cache

    if data_path is None:
        data_path = Path(__file__).parent / "data" / "reference_elements.json"

    try:
        with open(data_path, encoding="utf-8") as f:
            data = json.load(f)

        # Deserializar elementos
        elements = {}
        for symbol, element_data in data.get("elements", {}).items():
            elements[symbol] = _dict_to_element_reference(element_data)

        _reference_db_cache = ReferenceDatabase(
            elements=elements,
            version=data.get("version", "1.0"),
            source=data.get("source", "Unknown"),
        )

        return _reference_db_cache

    except (json.JSONDecodeError, KeyError) as e:
        print(f"Error cargando base de datos: {e}")
        return ReferenceDatabase(elements={})