Species Module

`Species`

Class of chemical species

This class generated species instances from the name of species. The name of species are like H2O, C2H6, etc. It parses the species name and find the substring matches with the recorded element/pseudo-element names. The list of element names can be set by the users (see methods below). Otherwise the default lists of element/pseudo-element are used.

!!! notes 1. Pseudo-element here is used to say the special symbols exist in species but not elements in periodic table, isotopes, charges. E.g. o(ortho-), p(para-), CR (cosmic-ray) 2. For surface species (species stick on grains), another special symbol are defined in surface_prefix. Species starts with the special symbol are denoted as surface species. 3. Charges must be +/- symbol append in the end. E.g. He++, Si+++

Attributes:

Name	Type	Description
`default_elements`	`list`	The default element names used to parse
`default_pseudoelement`	`list`	The default pseudo-element names
`surface_symbol`	`str`	The symbol used to define surface species.

`alias: str` `property` `writable`

Alias of the species.

Replace surface symbol by G and charges by M(-), I(+). Used in indexing species in codes. Can be customized by setter if needed.

`basename: str` `property` `readonly`

The species name without surface symbols and charges.

`binding_energy: float` `property` `readonly`

Binding energy of surface species.

Return the binding energy if this species is at ice-phase. If the binding energy was not set before, it will be searched in the UMIST 2012 binding energy data. Raise error when no value is found.

Exceptions:

Type	Description
`RuntimeError`	binding energy cannot be found

`charge: int` `property` `readonly`

Total charge of the species. Calculate the number of "+" and "-" in the end

`gasname: str` `property` `readonly`

Return the name of its gas-phase species if this species is at ice-phase. Else return the current name.

`is_surface: bool` `property` `readonly`

Check whether the species is sticking on surface (a surface species)

`mass: float` `property` `readonly`

The mass (amu) of the species, estimated by summing the mass of elements

`massnumber: float` `property` `readonly`

The mass number (neutron + proton) of the species

`photon_yield: float` `property` `readonly`

The photodesorption yield of the species (ice-phase only). Return default value (1.0e-3) if no value is found. The default value can be changed in naunet.chemistry.default_photon_yield

`add_known_elements(elements)` `classmethod`

Add names of elements to the list of known elements

Parameters:

Name	Type	Description	Default
`elements`	`list`	names of elements	required

Exceptions:

Type	Description
`TypeError`	If argument is not a list

Returns:

Type	Description
`list`	list: the current list of known elements

Source code in naunet/species.py

@classmethod
def add_known_elements(cls, elements: list) -> list:
    """
    Add names of elements to the list of known elements

    Args:
        elements (list): names of elements

    Raises:
        TypeError: If argument is not a list

    Returns:
        list: the current list of known elements
    """
    if not isinstance(elements, list):
        raise TypeError(f"{elements} is not a list")

    for ele in elements:
        if ele in cls._known_elements:
            logging.warning("{} exists in element list, skip!".format(ele))
        elif ele in cls._known_pseudoelements:
            logging.warning(
                "{} exists in pseudo element list, move to element list!".format(
                    ele
                )
            )
            cls._known_pseudoelements.remove(ele)
            cls._known_elements.append(ele)
        else:
            cls._known_elements.append(ele)
    cls._check_elements()
    return cls._known_elements

`add_known_pseudoelements(pelements)` `classmethod`

Add names of elements to the list of known pseudo elements

Parameters:

Name	Type	Description	Default
`pelements`	`list`	names of pseudo elements	required

Exceptions:

Type	Description
`TypeError`	If argument is not a list

Returns:

Type	Description
`list`	list: the current list of known pseudo elements

Source code in naunet/species.py

@classmethod
def add_known_pseudoelements(cls, pelements: list) -> list:
    """
    Add names of elements to the list of known pseudo elements

    Args:
        pelements (list): names of pseudo elements

    Raises:
        TypeError: If argument is not a list

    Returns:
        list: the current list of known pseudo elements
    """
    if not isinstance(pelements, list):
        raise TypeError(f"{pelements} is not a list")

    for ele in pelements:
        if ele in cls._known_pseudoelements:
            logging.warning("{} exists in pseudo element list, skip!".format(ele))
        elif ele in cls._known_elements:
            logging.warning(
                "{} exists in element list, move to pseudo element list!".format(
                    ele
                )
            )
            cls._known_elements.remove(ele)
            cls._known_pseudoelements.append(ele)
        else:
            cls._known_pseudoelements.append(ele)
    cls._check_elements()
    return cls._known_pseudoelements

`known_elements()` `classmethod`

Returns the current list of known elements

Returns:

Type	Description
`list`	list: the current list of known elements

Source code in naunet/species.py

@classmethod
def known_elements(cls) -> list:
    """
    Returns the current list of known elements

    Returns:
        list: the current list of known elements
    """
    return cls._known_elements

`known_pseudoelements()` `classmethod`

Returns the current list of known pseudo elements

Returns:

Type	Description
`list`	list: the current list of known pseudo elements

Source code in naunet/species.py

@classmethod
def known_pseudoelements(cls) -> list:
    """
    Returns the current list of known pseudo elements

    Returns:
        list: the current list of known pseudo elements
    """
    return cls._known_pseudoelements

`remove_known_elements(elements)` `classmethod`

Remove names of elements to the list of known elements

Parameters:

Name	Type	Description	Default
`elements`	`list`	names of elements	required

Exceptions:

Type	Description
`TypeError`	If argument is not a list

Returns:

Type	Description
`list`	list: the current list of known elements

Source code in naunet/species.py

@classmethod
def remove_known_elements(cls, elements: list) -> list:
    """
    Remove names of elements to the list of known elements

    Args:
        elements (list): names of elements

    Raises:
        TypeError: If argument is not a list

    Returns:
        list: the current list of known elements
    """
    if not isinstance(elements, list):
        raise TypeError(f"{elements} is not a list")

    for ele in elements:
        cls._known_elements.remove(ele)
    cls._check_elements()
    return cls._known_elements

`remove_known_pseudoelements(pelements)` `classmethod`

Add names of elements to the list of known pseudo elements

Parameters:

Name	Type	Description	Default
`pelements`	`list`	names of pseudo elements	required

Exceptions:

Type	Description
`TypeError`	If argument is not a list

Returns:

Type	Description
`list`	list: the current list of known pseudo elements

Source code in naunet/species.py

@classmethod
def remove_known_pseudoelements(cls, pelements: list) -> list:
    """
    Add names of elements to the list of known pseudo elements

    Args:
        pelements (list): names of pseudo elements

    Raises:
        TypeError: If argument is not a list

    Returns:
        list: the current list of known pseudo elements
    """
    if not isinstance(pelements, list):
        raise TypeError(f"{pelements} is not a list")

    for ele in pelements:
        cls._known_pseudoelements.remove(ele)
    cls._check_elements()
    return cls._known_pseudoelements

`reset()` `classmethod`

Reset class attributes in Species

Reset known_elements, known_pseudoelements, and surface_prefix.

Source code in naunet/species.py

@classmethod
def reset(cls) -> None:
    """Reset class attributes in Species

    Reset known_elements, known_pseudoelements, and surface_prefix.
    """
    cls._known_elements = []
    cls._known_pseudoelements = []
    cls.surface_prefix = "#"

`set_known_elements(elements)` `classmethod`

Set the list of known elements to new list

Parameters:

Name	Type	Description	Default
`elements`	`list`	names of elements	required

Exceptions:

Type	Description
`TypeError`	If argument is not a list

Returns:

Type	Description
`None`	list: the current list of known elements

Source code in naunet/species.py

@classmethod
def set_known_elements(cls, elements: list) -> None:
    """
    Set the list of known elements to new list

    Args:
        elements (list): names of elements

    Raises:
        TypeError: If argument is not a list

    Returns:
        list: the current list of known elements
    """
    if not isinstance(elements, list):
        raise TypeError(f"{elements} is not a list")

    cls._known_elements.clear()
    cls._known_elements.extend(elements)
    cls._check_elements()

`set_known_pseudoelements(pelements)` `classmethod`

Set the list of known pseudo elements to new list

Parameters:

Name	Type	Description	Default
`pelements`	`list`	names of pseudo elements	required

Exceptions:

Type	Description
`TypeError`	If argument is not a list

Returns:

Type	Description
`None`	list: the current list of known pseudo elements

Source code in naunet/species.py

@classmethod
def set_known_pseudoelements(cls, pelements: list) -> None:
    """
    Set the list of known pseudo elements to new list

    Args:
        pelements (list): names of pseudo elements

    Raises:
        TypeError: If argument is not a list

    Returns:
        list: the current list of known pseudo elements
    """
    if not isinstance(pelements, list):
        raise TypeError(f"{pelements} is not a list")

    cls._known_pseudoelements.clear()
    cls._known_pseudoelements.extend(pelements)
    cls._check_elements()

`top_abundant_species(species_list, abundances, element=None, rank=-1)`

The function returns a tuple list sorted by the abundances of element.

Parameters:

Name	Type	Description	Default
`species_list`	`list`	list of `Molecule()` objects.	required
`abundances`	`list`	The abundances of the species in the species_list.	required
`element`	`string`	The target element. The order is sorted by the abundances weighted by the number of element in the species. Defaults to None.	`None`
`rank`	`int`	Return the species in the top number. Defaults to -1 (all sorted species).	`-1`

Exceptions:

Type	Description
`RuntimeError`	The element could doesn't exist in the species_list and return an empty list.

Returns:

Type	Description
`list`	Tuple of `(Molecule, float)`.

Source code in naunet/species.py

def top_abundant_species(species_list, abundances, element=None, rank=-1):
    """
    The function returns a tuple list sorted by the abundances of element.

    Args:
        species_list (list): list of `Molecule()` objects.
        abundances (list): The abundances of the species in the species_list.
        element (string, optional): The target element. The order is sorted by the abundances weighted by the number of element in the species. Defaults to None.
        rank (int, optional): Return the species in the top number. Defaults to -1 (all sorted species).

    Raises:
        RuntimeError: The element could doesn't exist in the species_list and return an empty list.

    Returns:
        list: Tuple of `(Molecule, float)`.
    """
    sorted_abund = None
    if element == None:
        sorted_abund = sorted(
            zip(species_list, abundances), key=lambda x: x[1], reverse=True
        )[:rank]

    else:
        filtered_abund = list(
            filter(
                lambda x: element in x[0].element_count.keys(),
                zip(species_list, abundances),
            )
        )
        sorted_abund = sorted(
            filtered_abund,
            key=lambda x: x[1] * x[0].element_count[element],
            reverse=True,
        )[:rank]

    if not sorted_abund:
        raise RuntimeError(
            "Undefined results. please check the element exists in the network."
        )

    return sorted_abund

Species Module

Species

alias: str property writable

basename: str property readonly

binding_energy: float property readonly

charge: int property readonly

gasname: str property readonly

is_surface: bool property readonly

mass: float property readonly

massnumber: float property readonly

photon_yield: float property readonly

add_known_elements(elements) classmethod

add_known_pseudoelements(pelements) classmethod

known_elements() classmethod

known_pseudoelements() classmethod

remove_known_elements(elements) classmethod

remove_known_pseudoelements(pelements) classmethod

reset() classmethod

set_known_elements(elements) classmethod

set_known_pseudoelements(pelements) classmethod

top_abundant_species(species_list, abundances, element=None, rank=-1)

`Species`

`alias: str` `property` `writable`

`basename: str` `property` `readonly`

`binding_energy: float` `property` `readonly`

`charge: int` `property` `readonly`

`gasname: str` `property` `readonly`

`is_surface: bool` `property` `readonly`

`mass: float` `property` `readonly`

`massnumber: float` `property` `readonly`

`photon_yield: float` `property` `readonly`

`add_known_elements(elements)` `classmethod`

`add_known_pseudoelements(pelements)` `classmethod`

`known_elements()` `classmethod`

`known_pseudoelements()` `classmethod`

`remove_known_elements(elements)` `classmethod`

`remove_known_pseudoelements(pelements)` `classmethod`

`reset()` `classmethod`

`set_known_elements(elements)` `classmethod`

`set_known_pseudoelements(pelements)` `classmethod`

`top_abundant_species(species_list, abundances, element=None, rank=-1)`