Methods

App

build_thermodb(thermodb_name=None, message=None)

Build thermodb object to check and build thermodynamic data and equations

Parameters

thermodb_name : str name of the thermodb object - thermodb_name : str, name of the thermodb object message : str, optional a short description of the thermodb object, by default None

Returns

CompBuilder : object CompBuilder object used for building thermodynamic data and equations

Source code in pyThermoDB/app.py

def build_thermodb(
    thermodb_name: Optional[str] = None,
    message: Optional[str] = None
) -> CompBuilder:
    '''
    Build thermodb object to check and build thermodynamic data and equations

    Parameters
    ----------
    thermodb_name : str
        name of the thermodb object
        - `thermodb_name` : str, name of the thermodb object
    message : str, optional
        a short description of the thermodb object, by default None

    Returns
    -------
    CompBuilder : object
        CompBuilder object used for building thermodynamic data and equations
    '''
    try:
        # init class
        return CompBuilder(thermodb_name=thermodb_name, message=message)
    except Exception as e:
        raise Exception("Building thermodb failed!, ", e)

init(custom_reference=None)

Initialize thermodb app to check and build thermodynamic data and equations.

Parameters

custom_reference : dict | None, optional set-up external reference (custom reference) dict for databook and tables (check examples)

Returns

ThermoDB : object ThermoDB object used for checking and building data and equation objects

Notes

Set-up external reference dict for databook and tables

• format ref_external = {'yml':[yml files], 'csv':[csv files]}
• format ref_external = {'reference':[yml files], 'tables':[csv files]}

Examples

# custom ref
custom_reference = {
'reference': [yml_path],
'tables': [csv_path_1, csv_path_2]
}

# init app
tdb = ptdb.init(custom_reference=custom_reference)

Source code in pyThermoDB/app.py

def init(
    custom_reference: Optional[
        Dict[str, List[str | Dict[str, Any]]]
    ] = None
) -> ThermoDB:
    '''
    Initialize thermodb app to check and build thermodynamic data and equations.

    Parameters
    ----------
    custom_reference : dict | None, optional
        set-up external reference (custom reference) dict for databook and tables (check examples)

    Returns
    -------
    ThermoDB : object
        ThermoDB object used for checking and building data and equation objects

    Notes
    ------
    ### Set-up external reference dict for databook and tables

    - `format ref_external = {'yml':[yml files], 'csv':[csv files]}`
    - `format ref_external = {'reference':[yml files], 'tables':[csv files]}`

    ### Examples

    ```python
    # custom ref
    custom_reference = {
    'reference': [yml_path],
    'tables': [csv_path_1, csv_path_2]
    }

    # init app
    tdb = ptdb.init(custom_reference=custom_reference)
    ```
    '''
    try:
        # check new custom ref
        check_ref = False
        if custom_reference:
            CustomRefC = CustomRef(custom_reference)
            # check ref
            check_ref = CustomRefC.init_ref()

        # check
        if check_ref:
            return ThermoDB(CustomRefC)
        else:
            return ThermoDB()
    except Exception as e:
        raise Exception(f"Initializing app failed! {e}")

load_thermodb(thermodb_file)

Load thermodb object to read thermodynamic data and equations

Parameters

thermodb_file : str filename path

Returns

CompBuilder : object CompBuilder object used for loading thermodynamic data and equations

Source code in pyThermoDB/app.py

def load_thermodb(thermodb_file: str) -> CompBuilder:
    '''
    Load thermodb object to read thermodynamic data and equations

    Parameters
    ----------
    thermodb_file : str
        filename path

    Returns
    -------
    CompBuilder : object
        CompBuilder object used for loading thermodynamic data and equations
    '''
    try:
        # init class
        return CompBuilder.load(thermodb_file)
    except Exception as e:
        raise Exception("Loading thermodb failed!, ", e)

ref(custom_reference=None)

Checking references (custom reference) object including databook and tables to display data

Parameters

custom_reference : dict set-up external reference dict for databook and tables, format ref_external = {'yml':[yml files], 'csv':[csv files]}

Returns

TableReferenceC : object TableReference object used for checking references

Notes

Check external reference dict for databook and tables

• format ref_external = {'yml':[yml files], 'csv':[csv files]}
• format ref_external = {'reference':[yml files], 'tables':[csv files]}

Examples

# custom ref
custom_reference = {
'reference': [yml_path],
'tables': [csv_path_1, csv_path_2]
}

# init app
tdb = ptdb.ref(custom_reference=custom_reference)

Source code in pyThermoDB/app.py

def ref(
    custom_reference: Optional[
        Dict[str, List[str]]
    ] = None
) -> TableReference:
    '''
    Checking references (custom reference) object including databook and tables to display data

    Parameters
    ----------
    custom_reference : dict
        set-up external reference dict for databook and tables, format `ref_external = {'yml':[yml files], 'csv':[csv files]}`

    Returns
    -------
    TableReferenceC : object
        TableReference object used for checking references

    Notes
    ------
    ### Check external reference dict for databook and tables

    - `format ref_external = {'yml':[yml files], 'csv':[csv files]}`
    - `format ref_external = {'reference':[yml files], 'tables':[csv files]}`

    ### Examples

    ```python
    # custom ref
    custom_reference = {
    'reference': [yml_path],
    'tables': [csv_path_1, csv_path_2]
    }

    # init app
    tdb = ptdb.ref(custom_reference=custom_reference)
    ```
    '''
    try:
        # check new custom ref
        check_ref = False
        if custom_reference:
            CustomRefC = CustomRef(custom_reference)
            # check ref
            check_ref = CustomRefC.init_ref()

        # check
        if check_ref:
            return TableReference(custom_ref=CustomRefC)
        else:
            # init
            return TableReference()

    except Exception as e:
        raise Exception(f'Building reference failed! {e}')

Docs

thermo

ThermoDB

Bases: ManageData

Setting class

Source code in pyThermoDB/docs/thermo.py

class ThermoDB(ManageData):
    '''
    Setting class
    '''
    # selected databook
    __selected_databook = ''
    # selected table
    __selected_tb = ''

    def __init__(self, custom_ref=None, data_source='local'):
        self.data_source = data_source
        self.custom_ref = custom_ref
        # ManageData init
        ManageData.__init__(self, custom_ref=custom_ref)

    @property
    def selected_databook(self):
        return self.__selected_databook

    @selected_databook.setter
    def selected_databook(self, value):
        self.__selected_databook = value

    @property
    def selected_tb(self):
        return self.__selected_tb

    @selected_tb.setter
    def selected_tb(self, value):
        self.__selected_tb = value

    def list_symbols(
            self,
            res_format: Literal[
                'dict', 'list', 'dataframe', 'json'
            ] = 'dataframe'):
        '''
        List all symbols

        Parameters
        ----------
        res_format : Literal['dict', 'list', 'dataframe', 'json']
            Format of the returned data. Defaults to 'dataframe'.
        '''
        try:
            # load symbols
            res = self.get_symbols()

            # check format
            if res_format == 'dict':
                return res[0]
            elif res_format == 'list':
                return res[1]
            elif res_format == 'json':
                return res[2]
            elif res_format == 'dataframe':
                return res[3]
            else:
                raise ValueError('Invalid res_format')

        except Exception as e:
            raise Exception(f"Symbols loading error! {e}")

    def list_descriptions(
            self,
            res_format: Literal[
                'dict', 'list', 'dataframe', 'json'
            ] = 'dataframe'
    ) -> ListDatabookDescriptions:
        '''
        List all descriptions of databooks and tables

        Parameters
        ----------
        res_format : Literal['dict', 'list', 'dataframe', 'json']
            Format of the returned data. Defaults to 'dataframe'.

        Returns
        -------
        res : ListDatabookDescriptions
            List of descriptions in the specified format.
        '''
        try:
            # load descriptions
            res = self.get_descriptions()

            # check
            if res_format == 'dict':
                return res[0]
            elif res_format == 'list':
                return res[1]
            elif res_format == 'json':
                return res[2]
            elif res_format == 'dataframe':
                return res[3]
            else:
                raise ValueError('Invalid python res_format')

        except Exception as e:
            raise Exception(f"Descriptions loading error! {e}")

    def databook_info(
        self,
        databook: int | str,
        res_format: Literal[
            'dict', 'str', 'json'
        ] = 'json'
    ) -> Dict[str, str | Dict[str, str]] | str:
        '''
        Get information about a databook.

        Parameters
        ----------
        databook : int | str
            databook id or name
        res_format : Literal['dict', 'json']
            Format of the returned data. Defaults to 'dict'.

        Returns
        -------
        res : Dict[str, str | Dict[str, str]] | str
            Dictionary containing databook information or a string representation.
            - 'DATABOOK-ID': ID of the databook.
            - 'DATABOOK-NAME': Name of the databook.
            - 'DESCRIPTION': Description of the databook.
        '''
        try:
            # find databook
            db, db_name, db_id = self.find_databook(databook)

            # get databook info
            res = self.get_descriptions_by_databook(db_name)

            # check
            if res_format == 'dict':
                return res
            elif res_format == 'str':
                # convert to json
                return str(res)
            elif res_format == 'json':
                # convert to json
                return json.dumps(res, indent=4)
            else:
                logging.error('Invalid res_format')

            return res
        except Exception as e:
            raise Exception(f"Databook info loading error! {e}")

    def list_databooks(
            self,
            res_format: Literal[
                'list', 'dataframe', 'json'
            ] = 'dataframe'):
        '''
        List all databooks

        Parameters
        -----------
        res_format : Literal['list', 'dataframe', 'json']
            Format of the returned data. Defaults to 'dataframe'.

        Returns
        -------
        res : list | pandas.DataFrame | str
            Databook list in the specified format.
            - 'list': List of dictionaries containing databook information.
            - 'dataframe': Pandas DataFrame containing databook information.
            - 'json': JSON string representing the databook list.
        '''
        try:
            # databook list
            res = self.get_databooks()
            # check
            if res_format == 'list':
                return res[0]
            elif res_format == 'dataframe':
                return res[1]
            elif res_format == 'json':
                return res[2]
            else:
                raise ValueError('Invalid res_format')
        except Exception as e:
            raise Exception(f"databooks loading error! {e}")

    def list_tables(self,
                    databook: int | str,
                    res_format: Literal[
                        'list', 'dataframe', 'json', 'dict'
                    ] = 'dataframe'
                    ) -> list[list[str]] | pd.DataFrame | str | dict[str, str]:
        '''
        List all tables in the selected databook

        Parameters
        ----------
        databook : int | str
            databook id or name
        res_format : Literal['list', 'dataframe', 'json']
            Format of the returned data. Defaults to 'dataframe'.

        Returns
        -------
        table list : list | pandas.DataFrame | str | dict[str, str]
            list of tables
        '''
        try:
            # manual databook setting
            db, db_name, db_id = self.find_databook(databook)
            # table list
            res = self.get_tables(db_name)
            # check
            if res_format == 'list':
                return res[0]
            elif res_format == 'dataframe':
                return res[1]
            elif res_format == 'json':
                return res[2]
            elif res_format == 'dict':
                return res[3]
            else:
                raise ValueError('Invalid res_format')
        except Exception as e:
            raise Exception("Table loading error!,", e)

    def select_table(
        self,
        databook: int | str,
        table: int | str
    ) -> DataBookTableTypes:
        '''
        Select a table structure

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : int | str
            table id or name (non-zero-based id)
        dataframe: book
            if True, return a dataframe

        Returns
        -------
        tb : DataBookTableTypes
            table object
        '''
        try:
            # set
            tb_id = -1
            tb_name = ''

            # find databook
            db, db_name, db_id = self.find_databook(databook)

            # find table
            if isinstance(table, int):
                # tb
                tb = self.get_table(db_name, table-1)
            elif isinstance(table, str):
                # get tables
                tables = self.list_tables(databook=db_name, res_format='list')
                # check
                if isinstance(tables, list):
                    # looping
                    for i, item in enumerate(tables):
                        # check
                        if isinstance(item, list):
                            # table name
                            tb_name = item[0]
                            if tb_name == table.strip():
                                # zero-based id
                                tb_id = i
                                break
                        else:
                            raise ValueError(f"list {item} not found.")
                    # tb
                    # FIXME
                    tb = self.get_table(db, tb_id)
                else:
                    raise ValueError(f"table {table} not found.")
            else:
                raise ValueError("table must be int or str.")

            # res
            return tb
        except Exception as e:
            # Log or print the error for debugging purposes
            raise Exception(
                f"An error occurred while selecting the table: {e}")

    def table_description(
        self,
        databook: int | str,
        table: int | str,
        res_format: Literal[
            'str', 'json', 'dict'
        ] = 'str'
    ) -> str | dict:
        '''
        Get information about a databook.

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        res_format : Literal['str', 'json', 'dict']
            Format of the returned data. Defaults to 'str'.

        Returns
        -------
        str | dict
            Description of the table in the specified format.
            - 'str': Returns the description as a string.
            - 'dict': Returns a dictionary with the description.
            - 'json': Returns a JSON string with the description.
        '''
        try:
            # get the tb
            tb = self.select_table(databook, table)

            # check
            if tb:
                # descriptions
                descriptions = tb['description']

                # to dict
                des_dict = {
                    "table-description": descriptions
                }

                # check
                if descriptions:
                    # check
                    if res_format == 'str':
                        return descriptions
                    elif res_format == 'dict':
                        return des_dict
                    elif res_format == 'json':
                        return json.dumps(des_dict)
                    else:
                        raise ValueError('Invalid res_format')
                else:
                    return "No description found!"
            else:
                raise ValueError("No such table found!")

        except Exception as e:
            # Log or print the error for debugging purposes
            raise Exception(
                f"An error occurred while getting the databook info: {e}")

    def table_info(
        self,
        databook: int | str,
        table: int | str,
        res_format: Literal[
            'dict', 'dataframe', 'json'
        ] = 'dataframe'
    ) -> dict[str, int | str] | pd.DataFrame | str:
        '''
        Gives table contents as:

            * Table type
            * Data and equations numbers

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        dataframe: book
            if True, return a dataframe

        Returns
        -------
        tb_summary : dict | pandas.DataFrame | str
            table summary

        Notes
        -----
        1. The default value of dataframe is True, the return value (tb_summary) is Pandas Dataframe
        '''
        try:
            # table type
            tb_type = ''
            # table name
            table_name = ''
            # table equations
            table_equations = []
            # table data
            table_data = []
            # equation no
            equation_no = 0
            matrix_equation_no = 0
            # data no
            data_no = 0
            matrix_data_no = 0
            # get the tb
            tb = self.select_table(databook, table)

            # check
            if tb:
                # table name
                table_name: str = tb['table']
                # check
                if table_name is None:
                    raise Exception(f"table name {table_name} not found!")

                # check data/equations and matrix-data/matrix-equation
                # tb_type = 'Equation' if tb['equations'] is not None else 'Data'

                if tb['data'] is not None:
                    tb_type = 'Data'
                if tb['equations'] is not None:
                    tb_type = 'Equation'
                if tb['matrix_equations'] is not None:
                    tb_type = 'Matrix-Equation'
                if tb['matrix_data'] is not None:
                    tb_type = 'Matrix-Data'

                # ! check equations
                if tb_type == 'Equation' and tb['equations'] is not None:
                    for item in tb['equations']:
                        table_equations.append(item)

                    # equation no
                    equation_no = len(table_equations)

                # ! check data
                if tb_type == 'Data' and tb['data'] is not None:
                    table_data = [*tb['data']]

                    # data no
                    data_no = 1

                # ! check matrix-equation
                if tb_type == 'Matrix-Equation' and tb['matrix_equations'] is not None:
                    for item in tb['matrix_equations']:
                        table_equations.append(item)

                    # equation no
                    matrix_equation_no = len(table_equations)

                # ! check matrix-data
                if tb_type == 'Matrix-Data' and tb['matrix_data'] is not None:
                    # set
                    table_data = [*tb['matrix_data']]

                    # data no
                    matrix_data_no = 1

                # data
                tb_summary: Dict[str, str | int] = {
                    "Table Name": table_name,
                    "Type": tb_type,
                    "Equations": equation_no,
                    "Data": data_no,
                    "Matrix-Equations": matrix_equation_no,
                    "Matrix-Data": matrix_data_no
                }

                # json
                tb_summary_json = json.dumps(tb_summary)

            else:
                raise ValueError("No such table")

            if res_format == 'dataframe':
                # column names
                column_names = ['Table Name', 'Type', 'Equations',
                                'Data', 'Matrix-Equations', 'Matrix-Data']
                # dataframe
                df = pd.DataFrame([tb_summary], columns=column_names)
                return df
            elif res_format == 'json':
                return tb_summary_json
            elif res_format == 'dict':
                return tb_summary
            else:
                raise ValueError("Invalid res_format")
        except Exception as e:
            raise Exception(f"Table loading error {e}")

    def table_view(self, databook: str | int, table: str | int):
        '''
        Display a table header columns and other info

        Parameters
        ----------
        databook : str | int
            databook name or id
        table : str | int
            table name or id

        Returns
        -------
        str
            HTML content of the table view page.
        '''
        try:
            # SECTION: check if jinja2 is installed
            try:
                from jinja2 import Environment, FileSystemLoader
            except ImportError:
                raise ImportError(
                    "Jinja2 is not installed. Please install it using 'pip install jinja2'.")

            # SECTION: detect table type
            tb_info_res_ = self.table_info(databook, table, res_format='dict')

            # NOTE: databook name
            db, db_name, db_rid = self.find_databook(databook)

            # NOTE: table name
            tb_id, tb_name = self.find_table(databook, table)

            # res
            tb_res = None

            # if
            if isinstance(tb_info_res_, dict):
                # check
                if tb_info_res_['Type'] == 'Equation':  # ! equation
                    # load table equation
                    tb_res = self.table_data(databook, table)
                elif tb_info_res_['Type'] == 'Data':  # ! data
                    # load table data
                    tb_res = self.table_data(databook, table)
                elif tb_info_res_['Type'] == 'Matrix-Equation':  # ! matrix-equation
                    # load table equation
                    tb_res = self.table_data(databook, table)
                elif tb_info_res_['Type'] == 'Matrix-Data':  # ! matrix-data
                    # load table equation
                    tb_res = self.table_data(databook, table)
                else:
                    raise Exception('No data/equation found!')

                # SECTION: convert dataframe to dict
                # check
                if isinstance(tb_res, pd.DataFrame):
                    # NOTE: convert to list of dict
                    tb_res = tb_res.to_dict(orient='records')

                # SECTION: web application
                # check jinja2 installed
                # from jinja2 import Environment, FileSystemLoader
                # res
                # return tb_res
                # NOTE: tojson function
                def tojson(obj):
                    return json.dumps(obj)

                # NOTE: url_for function
                def url_for(endpoint, filename=None):
                    """
                    Generate absolute paths for static files when opening the HTML file directly.
                    """
                    if endpoint == 'static':
                        # Get the directory of the current script
                        # current path
                        current_path = os.path.dirname(__file__)

                        # Go back to the parent directory (pyThermoDB)
                        parent_path = os.path.abspath(
                            os.path.join(current_path, '..'))

                        # static path
                        static_path = os.path.join(parent_path, 'static')

                        # base_dir = os.path.dirname(os.path.abspath(__file__))
                        # parent_dir = os.path.dirname(os.path.dirname(__file__))
                        # static directory
                        static_dir = f'file://{os.path.join(static_path, filename).replace(os.sep, "/")}'
                        return static_dir
                    return '#'

                def render_page(databook_name: str,
                                table_name: str,
                                sample_data: List[Dict],
                                page: int = 1,
                                rows_per_page: int = 50,
                                theme: Literal['light', 'dark'] = "light"):
                    """
                    Render the HTML page using Jinja2 templates

                    Parameters
                    ----------
                    databook_name : str
                        Name of the databook
                    table_name : str
                        Name of the table
                    sample_data : list
                        List of dictionaries containing table data
                    page : int, optional
                        Current page number (default is 1)
                    rows_per_page : int, optional
                        Number of rows per page (default is 50)
                    theme : str, optional
                        Theme for the table ('light' or 'dark', default is 'light')
                    """
                    # Define text colors for each theme to ensure visibility
                    text_colors = {
                        'light': {
                            'primary': '#212529',  # Dark text for light backgrounds
                            'secondary': '#495057',
                            'muted': '#6c757d'
                        },
                        'dark': {
                            'primary': '#f8f9fa',  # Light text for dark backgrounds
                            'secondary': '#e9ecef',
                            'muted': '#adb5bd'
                        }
                    }

                    # extract data
                    sample_data = sample_data[2:]
                    # Calculate pagination values
                    total_items = len(sample_data)
                    total_pages = (
                        total_items + rows_per_page - 1) // rows_per_page

                    # SECTION: Setup Jinja2 environment
                    # current path
                    current_path = os.path.dirname(__file__)

                    # Go back to the parent directory (pyThermoDB)
                    parent_path = os.path.abspath(
                        os.path.join(current_path, '..'))

                    # template path
                    template_path = os.path.join(parent_path, 'templates')

                    template_loader = FileSystemLoader(
                        searchpath=template_path)
                    template_env = Environment(loader=template_loader)

                    # Add the function to Jinja2 environment globals
                    template = template_env.get_template('table_view.html')

                    # SECTION: Get the template and render it with the data
                    rendered_html = template.render(
                        title='PyThermoDB Table Viewer',
                        app_name='PyThermoDB Viewer',
                        databook_name=databook_name,
                        table_name=table_name,
                        table_title='Chemical Compounds Data',
                        table_data=sample_data,
                        total_data=total_items,
                        tojson=tojson,
                        url_for=url_for,
                        current_page=page,
                        rows_per_page=rows_per_page,
                        total_pages=total_pages,
                        default_theme=theme,
                        text_colors=text_colors,
                        footer_text=(
                            'PyThermoDB Table Viewer - A web application to display and '
                            'interact with thermodynamic data tables.'
                        ),
                        company='PyThermoDB Project',
                        app_version=__version__,
                    )

                    return rendered_html

                # generate HTML content for the requested page
                html_content = render_page(
                    db_name,
                    tb_name,
                    tb_res,
                    page=1,
                    rows_per_page=50,
                    theme='light'
                )

                # temporary file to store the HTML content
                with tempfile.NamedTemporaryFile(
                    'w', delete=False, suffix='.html'
                ) as temp_file:
                    temp_file.write(html_content)
                    # NOTE: the file is not deleted after closing, so we can open it in the
                    # browser
                    webbrowser.open(temp_file.name)

                # Return the path to the temporary file in case needed elsewhere
                return temp_file.name

            else:
                raise Exception('Table loading error!')
        except Exception as e:
            raise Exception(f"Table loading error {e}")

    def tables_view(self):
        """
        Display all tables in the browser.
        """
        try:
            # SECTION: check if jinja2 is installed
            try:
                from jinja2 import Environment, FileSystemLoader
            except ImportError:
                raise ImportError(
                    "Jinja2 is not installed. Please install it using 'pip install jinja2'.")

            # SECTION: load data
            data_ = self.list_descriptions(res_format='dict')

            # check
            if not isinstance(data_, dict):
                raise ValueError("data_ is not a dictionary!")

            # card data
            card_data = []

            # looping through databooks
            for k, v in data_.items():
                db_name = k
                db_id = v['DATABOOK-ID']

                # looping through tables
                for k_, v_ in v.items():
                    if k_ == 'DATABOOK-ID':
                        continue

                    _table_id = v_['TABLE-ID']
                    _table_description = v_['DESCRIPTION']
                    _table_name = k_

                    # data load
                    _table_data = self.table_data(
                        db_id, _table_id, res_format='list')

                    # collect data
                    card_data.append({
                        'db_name': db_name,
                        'db_id': db_id,
                        'table_name': _table_name,
                        'table_id': _table_id,
                        'table_description': _table_description,
                        'table_data': _table_data,
                        'table_data_length': len(_table_data),
                    })

            # SECTION: render HTML page
            # init launcher
            app = Launcher()
            # pass data
            return app.launch(card_data)

        except Exception as e:
            raise Exception(f"Error displaying tables: {e}")

    def table_data(
        self,
        databook: str | int,
        table: str | int,
        res_format: Literal[
            'dataframe', 'list', 'json'
        ] = 'dataframe'
    ) -> pd.DataFrame | List[
        Dict[Hashable, Optional[float | int | str]]
    ] | str | Dict[str, pd.DataFrame]:
        '''
        Get all table elements (display a table)

        Parameters
        ----------
        databook : str | int
            databook name or id
        table : str | int
            table name or id
        res_format : Literal['dataframe', 'dict','json']
            Format of the returned data. Defaults to 'dataframe'.

        Returns
        -------
        tb_data : Pandas.DataFrame | list | str
            table data in the specified format.
        '''
        try:
            # find databook zero-based id (real)
            db, db_name, db_rid = self.find_databook(databook)
            # databook id
            databook_id = db_rid + 1

            # find table zero-based id
            tb_id, tb_name = self.find_table(databook, table)
            # table id
            table_id = tb_id + 1

            # SECTION: set api
            TableReferenceC = TableReference(custom_ref=self.custom_ref)
            # REVIEW: load table
            tb_data = TableReferenceC.load_table(databook_id, table_id)

            # NOTE: check tb_data
            if isinstance(tb_data, pd.DataFrame):
                # ! dataframe
                # convert to list of dicts
                tb_list_dict = tb_data.to_dict(orient='records')
                # to json
                tb_json = tb_data.to_json(orient='records')

                # NOTE: check res_format
                if res_format == 'dataframe':
                    return tb_data
                elif res_format == 'list':
                    return tb_list_dict
                elif res_format == 'json':
                    return tb_json
                else:
                    raise ValueError('Invalid res_format')
            else:
                raise ValueError('Invalid table data format')
        except Exception as e:
            raise Exception(f"Loading matrix data failed {e}")

    def equation_load(
        self,
        databook: int | str,
        table: int | str
    ) -> TableEquation:
        '''
        Display table header columns and other info

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : str
            table name

        Returns
        -------
        object: TableEquation

        Notes
        -----
        1. table should be a string
        '''
        try:
            # table type
            # tb_type = ''
            # table name
            table_name = ''
            # table equations
            table_equations = []
            # databook id | name
            db, db_name, db_id = self.find_databook(databook)
            # get the tb
            tb = self.select_table(databook, table)

            # check
            if tb:
                # NOTE: table name
                table_name = tb['table']

                # NOTE: table type
                if tb['table_type'] is not None and tb['table_type'] != 'None':
                    tb_type = TableTypes.EQUATIONS.value

                # NOTE: table values
                if tb['table_values'] is not None and tb['table_values'] != 'None':
                    table_values = tb['table_values']
                else:
                    table_values = None

                # NOTE: table structure
                if tb['table_structure'] is not None and tb['table_structure'] != 'None':
                    table_structure = tb['table_structure']
                else:
                    table_structure = None

                # check data/equations
                if tb['equations'] is not None and tb['equations'] != 'None':
                    # set table type
                    # tb_type = 'equation'

                    # looping through equations
                    for item in tb['equations']:
                        table_equations.append(item)

                    # create table equation
                    return TableEquation(
                        db_name,
                        table_name,
                        table_equations,
                        table_values=table_values,
                        table_structure=table_structure
                    )
                else:
                    raise Exception('Table loading error!')
            else:
                raise Exception('Table loading error!')

        except Exception as e:
            raise Exception(f"Table loading error {e}")

    def data_load(
        self,
        databook: int | str,
        table: int | str
    ) -> TableData:
        '''
        Display table header columns and other info

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : str
            table name

        Returns
        -------
        object : TableData
            table object with data loaded
        '''
        try:
            # table type
            tb_type = ''
            # table name
            table_name = ''
            # table data
            table_data = []
            # databook id | name
            db, db_name, db_id = self.find_databook(databook)
            # get the tb
            tb = self.select_table(databook, table)

            # check
            if tb:
                # NOTE: table name
                table_name = tb['table']

                # NOTE: check data/equations
                if tb['data'] is None or tb['data'] == 'None':
                    raise Exception(
                        'This method not compatible with the selected table!')

                tb_type = TableTypes.DATA.value

                # NOTE: check table values
                if tb['table_values'] is not None and tb['table_values'] != 'None':
                    table_values = tb['table_values']
                else:
                    table_values = None

                # NOTE: check table structure
                if tb['table_structure'] is not None and tb['table_structure'] != 'None':
                    table_structure = tb['table_structure']
                else:
                    table_structure = None

                # check data
                if tb_type == 'data':
                    table_data = tb['data']

                    # check
                    if not isinstance(table_data, dict):
                        raise ValueError("Table data is not a dictionary!")

                    # extract table data
                    COLUMNS = table_data.get('COLUMNS')
                    SYMBOL = table_data.get('SYMBOL')
                    UNIT = table_data.get('UNIT')
                    CONVERSION = table_data.get('CONVERSION')

                    # NOTE: check if the table data is empty
                    if not COLUMNS or not SYMBOL or not UNIT or not CONVERSION:
                        raise ValueError("Table data is empty!")

                    # data no
                    return TableData(
                        db_name,
                        table_name,
                        table_data,
                        table_values=table_values,
                        table_structure=table_structure
                    )
                else:
                    raise Exception('Table loading error!')
            else:
                raise Exception('Table loading error!')
        except Exception as e:
            raise Exception(f"Table loading error {e}")

    def matrix_equation_load(
        self,
        databook: int | str,
        table: int | str
    ) -> TableMatrixEquation:
        '''
        Display table header columns and other info

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : str
            table name

        Returns
        -------
        object: TableMatrixEquation

        Notes
        -----
        1. table should be a string
        '''
        try:
            # table type
            # tb_type = ''
            # table name
            table_name = ''
            # table equations
            table_equations = []
            # databook id | name
            db, db_name, db_id = self.find_databook(databook)
            # get the tb
            tb = self.select_table(databook, table)

            # check
            if tb:
                # table name
                table_name = tb['table']

                # matrix-data/matrix-equation
                if tb['matrix_equations'] is not None:
                    # tb_type = TableTypes.MATRIX_EQUATIONS.value

                    for item in tb['matrix_equations']:
                        table_equations.append(item)

                    # create table equation
                    return TableMatrixEquation(
                        db_name,
                        table_name,
                        table_equations
                    )
                else:
                    raise Exception('Table loading error!')
            else:
                raise Exception('Table loading error!')

        except Exception as e:
            raise Exception(f"Table loading error {e}")

    def matrix_data_load(
        self,
        databook: int | str,
        table: int | str
    ) -> TableMatrixData:
        '''
        Gives table contents as:

            * Table type
            * Data and equations numbers

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : str
            table name

        Returns
        -------
        object : TableMatrixData
            table object with data loaded
        '''
        try:
            # table type
            # tb_type = ''
            # table name
            table_name = ''
            # table data
            table_data = []
            # databook id | name
            db, db_name, db_id = self.find_databook(databook)
            # get the tb
            tb = self.select_table(databook, table)

            # check
            if tb:
                # table name
                table_name = tb['table']

                # matrix-data/matrix-equation
                if tb['matrix_data'] is not None:
                    # tb_type = TableTypes.MATRIX_DATA.value

                    # table data
                    table_data = tb['matrix_data']

                    # data no
                    return TableMatrixData(db_name, table_name, table_data)
                else:
                    raise Exception('Table loading error!')
            else:
                raise Exception('Table not found!')
        except Exception as e:
            raise Exception(f"Table loading error {e}")

    def check_component(
            self,
            component_name: str | list[str],
            databook: int | str,
            table: int | str,
            column_name: Optional[str | list[str]] = None,
            query: bool = False,
            res_format: Literal[
                'dict', 'json', 'str'
            ] = 'json'
    ) -> Union[str, dict[str, str]]:
        '''
        Check a component availability in the selected databook and table

        Parameters
        ----------
        component_name : str | list
            string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g']
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        column_name : str | list
            column name (e.g. 'Name') | list as ['Name','state']
        query : str
            query to search a dataframe

        Returns
        -------
        str | dict[str, str]
            summary of the component availability
        '''
        try:
            # NOTE: check search option
            if column_name is None:
                column_name = 'Name'

            # NOTE: check
            if query:
                column_name = column_name

            # SECTION: find ids
            # find databook zero-based id (real)
            db, db_name, db_rid = self.find_databook(databook)
            # databook id (non-zero-based id)
            databook_id = db_rid + 1

            # find table zero-based id
            tb_id, tb_name = self.find_table(databook, table)
            # table id (non-zero-based id)
            table_id = tb_id + 1

            # res
            res = False

            # check databook_id and table_id are number or not
            if isNumber(databook_id) and isNumber(table_id):
                # check
                if self.data_source == 'api':
                    # res = self.check_component_api(
                    #     component_name, databook_id, table_id)
                    pass
                elif self.data_source == 'local':
                    res = self.check_component_local(
                        component_name=component_name,
                        databook_id=databook_id,
                        table_id=table_id,
                        column_name=column_name,
                        query=query
                    )
                else:
                    raise Exception('Data source error!')
            else:
                raise Exception("databook and table id required!")

            # res
            res_dict = {
                'databook_id': databook_id,
                'databook_name': db_name,
                'table_id': table_id,
                'table_name': tb_name,
                'component_name': component_name,
                'availability': res
            }

            # json
            res_json = json.dumps(res_dict, indent=4)

            # check
            if res_format == 'json':
                return res_json
            elif res_format == 'dict':
                return res_dict
            elif res_format == 'str':
                return res_json
            else:
                raise ValueError('Invalid res_format')
        except Exception as e:
            raise Exception(f"Component check error! {e}")

    def is_component_available(
        self,
        component: Component,
        databook: int | str,
        table: int | str,
        column_names: List[str] = ['Name', 'Formula'],
        component_key: Literal['Name-State', 'Formula-State'] = 'Name-State',
        res_format: Literal['dict', 'json', 'str'] = 'dict'
    ) -> Union[str, dict[str, str]]:
        '''
        Check if a component is available in the specified databook and table. A component is defined as:
        - name-state: carbon dioxide-g
        - formula-state: CO2-g

        Parameters
        ----------
        component : Component
            The component to check.
        databook : int | str
            The databook id or name.
        table : int | str
            The table id or name.
        column_names : List[str], optional
            List of column names to search in, by default ['Name', 'Formula'].
        component_key : Literal['Name-State', 'Formula-State'], optional
            The key to use for identifying the component, by default 'Name-State'.
        res_format : Literal['dict', 'json', 'str'], optional
            The format of the returned result, by default 'json'.

        Returns
        -------
        str | dict[str, str]
            Summary of the component availability.

        Notes
        -----
        - Table should contain columns for 'Name', 'Formula', and 'State'. Otherwise an error will be raised.
        '''
        try:
            # SECTION: Validate input
            if not isinstance(component, Component):
                raise ValueError(
                    "Invalid component. Must be an instance of Component class.")
            if (
                not component.name and
                not component.formula and
                not component.state
            ):
                raise ValueError(
                    "Component must have at least a name or a formula.")
            if not column_names or not isinstance(column_names, list):
                raise ValueError(
                    "column_names must be a non-empty list of strings.")
            if len(column_names) != 2:
                raise ValueError(
                    "column_names must contain exactly two elements: ['Name', 'Formula'].")

            # SECTION: Check component_key validity
            if component_key not in ['Name-State', 'Formula-State']:
                raise ValueError(
                    "Invalid component_key. Must be 'Name-State' or 'Formula-State'.")

            # NOTE: create component id band query
            component_id = None
            query = None

            # check
            if component_key == 'Name-State':
                # set
                component_id = f"{component.name}-{component.state}"
                # query
                query = f'Name.str.lower() == "{component.name.lower()}" and State.str.lower() == "{component.state.lower()}"'
            elif component_key == 'Formula-State':
                # set
                component_id = f"{component.formula}-{component.state}"
                # query
                query = f'Formula.str.lower() == "{component.formula.lower()}" and State.str.lower() == "{component.state.lower()}"'

            if component_id is None:
                raise ValueError("Component ID could not be determined.")

            if query is None:
                raise ValueError("Query could not be determined.")

            # SECTION: find ids
            # find databook zero-based id (real)
            db, db_name, db_rid = self.find_databook(databook)
            # databook id (non-zero-based id)
            databook_id = db_rid + 1

            # find table zero-based id
            tb_id, tb_name = self.find_table(databook, table)
            # table id (non-zero-based id)
            table_id = tb_id + 1

            # SECTION: Check if the component exists in the specified databook and table
            availability = self.check_component_local(
                component_name=component_id,
                databook_id=databook_id,
                table_id=table_id,
                column_name=query,
                query=True,
            )

            # res
            res_dict = {
                'databook_id': databook_id,
                'databook_name': db_name,
                'table_id': table_id,
                'table_name': tb_name,
                'component_name': component_id,
                'availability': availability
            }

            # json
            res_json = json.dumps(res_dict, indent=4)

            # check
            if res_format == 'json':
                return res_json
            elif res_format == 'dict':
                return res_dict
            elif res_format == 'str':
                return res_json
            else:
                raise ValueError('Invalid res_format')
        except Exception as e:
            raise Exception(f"Error checking component availability: {e}")

    def check_component_api(
            self,
            component_name: str | list,
            databook_id: int,
            table_id: int):
        '''
        Check component availability in the selected databook and table

        Parameters
        ----------
        component_name : str | list
            string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g']
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str | list
            column name (e.g. 'Name') | list as ['Name','state']

        Returns
        -------
        comp_info : str
            component information
        '''
        try:
            # check databook_id and table_id are number or not
            if isNumber(databook_id) and isNumber(table_id):
                # set api
                ManageC = Manage(API_URL, databook_id, table_id)
                # search
                compList = ManageC.component_list()
                # check availability
                # uppercase list
                compListUpper = uppercaseStringList(compList)
                if len(compList) > 0:
                    # get databook
                    databook_name = self.list_databooks(res_format='list')[
                        databook_id-1]
                    # get table
                    # table_name = self.list_tables(databook=databook_id, res_format='list')[
                    #     table_id-1][0]

                    list_tables_ = self.list_tables(
                        databook=databook_id,
                        res_format='list'
                    )

                    # set
                    table_id_ = table_id - 1

                    # check
                    if len(list_tables_) > 0:
                        # get table name

                        table_name = "Obsolete Table"

                    # check
                    # if component_name.upper() in compListUpper:
                    #     print(
                    #         f"[{component_name}] available in [{table_name}] | [{databook_name}]")
                    # else:
                    #     print(f"{component_name} is not available.")
                else:
                    print("API error. Please try again later.")

                return None
            else:
                raise Exception(
                    "Invalid input. Please check the input type (databook_id and table_id).")
        except Exception as e:
            raise Exception(f'Checking data error {e}')

    def check_component_local(
        self,
        component_name: str | list,
        databook_id: int,
        table_id: int,
        column_name: str | list[str],
        query: bool = False,
        verbose: bool = False
    ) -> bool:
        '''
        Check component availability in the selected databook and table

        Parameters
        ----------
        component_name : str | list
            string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g']
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str
            column name (e.g. 'Name') | list
        query : str
            query string (e.g. 'Name == "Carbon dioxide"')

        Returns
        -------
        object : bool
            component information

        Notes
        -----
        - Return True if df is not empty
        - Return False if df is empty
        '''
        try:
            # check databook_id and table_id are number or not
            if (
                isNumber(databook_id) and
                isNumber(table_id)
            ):
                # set api
                TableReferenceC = TableReference(custom_ref=self.custom_ref)

                # NOTE: search
                df = TableReferenceC.search_tables(
                    databook_id=databook_id,
                    table_id=table_id,
                    column_name=column_name,
                    lookup=component_name,  # ! exact match
                    query=query
                )

                # NOTE: check availability
                if len(df) > 0:
                    if verbose:
                        print(
                            f"[{component_name}] available in [{table_id}] | [{databook_id}]"
                        )

                    # res
                    return True
                else:
                    # log
                    if verbose:
                        print(f"{component_name} is not available.")

                    # res
                    return False
            else:
                logger.error(
                    "Invalid input. Please check the input type (databook_id and table_id).")
                return False
        except Exception as e:
            logger.error(f'Checking data error {e}')
            return False

    def get_component_data(
        self,
        component_name: str,
        databook_id: int,
        table_id: int,
        column_name: Optional[str | list[str]] = None,
        dataframe: bool = False,
        query: bool = False,
        matrix_tb: bool = False,
        component_state: Optional[str] = None
    ):
        '''
        Get component data from database (api|local csvs)

        Parameters
        ----------
        component_name : str
            string of component name (e.g. 'Carbon dioxide')
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str | list, optional
            column name
        dataframe : bool
            return dataframe or not
        query : bool
            query or not
        matrix_tb : bool
            matrix table or not
        component_state : str, optional
            component state (e.g. 'g', 'l', 's')

        Returns
        -------
        component_data : object | pandas dataframe
            component data
        '''
        try:
            # check search option
            if column_name is None:
                column_name = 'Name'

            # set
            component_name = str(component_name).strip()
            # check datasource
            if self.data_source == 'api':
                # component_data = self.get_component_data_api(
                #     component_name, databook_id, table_id, column_name,
                #     dataframe=dataframe)
                return None
            elif self.data_source == 'local':
                component_data = self.get_component_data_local(
                    component_name=component_name,
                    databook_id=databook_id,
                    table_id=table_id,
                    column_name=column_name,
                    component_state=component_state,
                    dataframe=dataframe,
                    query=query,
                    matrix_tb=matrix_tb
                )
            else:
                raise Exception('Data source error!')
            # res
            return component_data
        except Exception as e:
            raise Exception(f"Loading data failed {e}")

    def get_component_data_api(
            self,
            component_name: str,
            databook_id: int,
            table_id: int,
            dataframe: bool = False
    ):
        '''
        Get component data from database (api)

        It consists of:
            step1: get thermo data for a component,
            step2: get equation for the data (parameters).

        Parameters
        ----------
        component_name : str
            string of component name (e.g. 'Carbon dioxide')
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str
            column name
        dataframe : bool
            return dataframe or not

        Returns
        -------
        component_data : object | pandas dataframe
            component data
        '''
        # set api
        ManageC = Manage(API_URL, databook_id, table_id)
        # search
        component_data = ManageC.component_info(component_name)
        # check availability
        if len(component_data) > 0:
            # check
            if dataframe:
                df = pd.DataFrame(component_data, columns=[
                    'header', 'symbol', 'records', 'unit'])
                return df
            else:
                return component_data
        else:
            print(f"Data for {component_name} not available!")
            return {}

    def get_component_data_local(
        self,
        component_name: str,
        databook_id: int,
        table_id: int,
        column_name: str | list[str],
        component_state: Optional[str] = None,
        dataframe: bool = False,
        query: bool = False,
        matrix_tb: bool = False
    ):
        '''
        Get component data from database (local csv files)

        Parameters
        ----------
        component_name : str
            string of component name (e.g. 'Carbon dioxide')
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str
            column name | query to find a record from a dataframe
        component_state : str, optional
            component state (e.g. 'g', 'l', 's')
        dataframe : bool
            return dataframe or not
        query : bool
            query or not
        matrix_tb : bool
            matrix table or not

        Returns
        -------
        payload : dict | pandas dataframe
            component information
        '''
        try:
            # check databook_id and table_id are number or not
            if isNumber(databook_id) and isNumber(table_id):
                # set api
                TableReferenceC = TableReference(custom_ref=self.custom_ref)

                # NOTE: set query
                if component_state is not None:
                    # ! set column_name
                    if isinstance(column_name, str):
                        column_name = [column_name, 'State']
                    elif isinstance(column_name, list):
                        if 'State' not in column_name:
                            column_name.append('State')

                    # ! set query
                    if isinstance(component_name, str):
                        lookup = [component_name, component_state]
                else:
                    lookup = component_name

                # NOTE: search
                try:
                    payload = TableReferenceC.make_payload(
                        databook_id=databook_id,
                        table_id=table_id,
                        column_name=column_name,
                        lookup=lookup,
                        query=query,
                        matrix_tb=matrix_tb
                    )
                except Exception as e:
                    logging.error(f"Table search error {e}")
                    payload = None

                # NOTE: check availability
                if payload:
                    # check
                    if len(payload) > 0:
                        if dataframe:
                            df = pd.DataFrame(
                                payload,
                                columns=[
                                    'header', 'symbol', 'records', 'unit'
                                ]
                            )
                            return df
                        else:
                            return payload
                    else:
                        raise Exception(
                            "Data for {} not available!".format(component_name))
                else:
                    raise Exception(
                        "Data for {} not available!".format(component_name))
            else:
                print("databook and table id required!")
        except Exception as e:
            raise Exception(f'Reading data error {e}')

    def build_thermo_property(
        self,
        component_names: list[str],
        databook: int | str,
        table: int | str,
        **kwargs
    ) -> ThermoProperty:
        """
        Build a thermodynamic property including data, equation, matrix-data and matrix-equation.

        Parameters
        ----------
        component_names :  list[str]
            list of component name (e.g. 'Carbon dioxide')
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        **kwargs
            Additional keyword arguments to pass to the specific build methods.
            - component_state : str, optional
                component state (e.g. 'g', 'l', 's')

        Returns
        -------
        ThermoProperty
            table object with data loaded
            - TableEquation
            - TableData
            - TableMatrixEquation
            - TableMatrixData
        """
        try:
            # SECTION: extract kwargs
            # LINK: column name
            column_name = kwargs.get('column_name', None)
            # LINK: query
            query = kwargs.get('query', False)

            # SECTION: detect table type
            tb_info_res_ = self.table_info(databook, table, res_format='dict')

            # SECTION: build thermo property
            if isinstance(tb_info_res_, dict):
                # check
                if tb_info_res_['Type'] == 'Equation':  # ! equation
                    # check
                    if len(component_names) > 1:
                        raise Exception('Only one component name required!')

                    # component name set
                    component_name_ = component_names[0]

                    # build equation
                    return self.build_equation(
                        component_name=component_name_,
                        databook=databook,
                        table=table,
                        column_name=column_name,
                    )
                elif tb_info_res_['Type'] == 'Data':  # ! data
                    # check
                    if len(component_names) > 1:
                        raise Exception('Only one component name required!')

                    # component name set
                    component_name_ = component_names[0]

                    # build data
                    return self.build_data(
                        component_name=component_name_,
                        databook=databook,
                        table=table,
                        column_name=column_name,
                    )
                elif tb_info_res_['Type'] == 'Matrix-Equation':  # ! matrix-equation
                    # check
                    if len(component_names) < 2:
                        raise Exception(
                            'At least two component names required!')
                    # build matrix-equation
                    return self.build_matrix_equation(
                        component_names,
                        databook,
                        table
                    )
                elif tb_info_res_['Type'] == 'Matrix-Data':  # ! matrix-data
                    # check
                    if len(component_names) < 2:
                        raise Exception(
                            'At least two component names required!')
                    # build matrix-data
                    return self.build_matrix_data(
                        component_names,
                        databook,
                        table
                    )
                else:
                    raise Exception('No data/equation found!')
            else:
                raise Exception('Table loading error!')
        except Exception as e:
            raise Exception(f'Building thermo property error {e}')

    def build_components_thermo_property(
        self,
        components: List[Component],
        databook: int | str,
        table: int | str,
        component_key: Literal[
            'Name-State', 'Formula-State'
        ] = 'Name-State',
    ) -> ThermoProperty:
        '''
        Build thermo property for a component including data, equation, matrix-data and matrix-equation.

        Parameters
        ----------
        components : str
            string of component name (e.g. 'Carbon dioxide')
        component_state : str, optional
            component state (e.g. 'g', 'l', 's')
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        component_key : Literal['Name-State', 'Formula-State'], optional
            The key to use for identifying the component, by default 'Name-State'.

        Returns
        -------
        ThermoProperty
            table object with data loaded
            - TableEquation
            - TableData
            - TableMatrixEquation
            - TableMatrixData

        Notes
        -----
        - Table should contain columns for 'Name', 'Formula', and 'State'. Otherwise an error will be raised.
        - For 'Equation' and 'Data' types, only one component should be provided.
        - For 'Matrix-Equation' and 'Matrix-Data' types, at least two components should be provided.
        - The `component_key` parameter determines whether to use the component's name or formula along
        '''
        try:
            # NOTE: detect table type
            tb_info_res_ = self.table_info(databook, table, res_format='dict')

            # SECTION: build thermo property
            if isinstance(tb_info_res_, dict):
                # check
                if tb_info_res_['Type'] == 'Equation':  # ! equation

                    # NOTE: check components
                    if len(components) != 1:
                        raise Exception('Only one component required!')

                    if not isinstance(components[0], Component):
                        raise Exception('Invalid component!')

                    # set component id
                    component_id_ = None
                    component_state_ = components[0].state
                    column_id_ = None

                    # NOTE: set component id and column id
                    if component_key == 'Name-State':
                        component_id_ = components[0].name
                        column_id_ = 'Name'
                    elif component_key == 'Formula-State':
                        component_id_ = components[0].formula
                        column_id_ = 'Formula'
                    else:
                        raise Exception('Invalid component_key!')

                    # NOTE: build equation
                    return self.build_equation(
                        component_name=component_id_,
                        databook=databook,
                        table=table,
                        column_name=column_id_,
                        component_state=component_state_,
                    )
                elif tb_info_res_['Type'] == 'Data':  # ! data
                    # check
                    if len(components) > 1:
                        raise Exception('Only one component name required!')

                    if not isinstance(components[0], Component):
                        raise Exception('Invalid component!')

                    # NOTE: set component id
                    component_id_ = None
                    component_state_ = components[0].state
                    column_id_ = None

                    # NOTE: set component id and column id
                    if component_key == 'Name-State':
                        component_id_ = components[0].name
                        column_id_ = 'Name'
                    elif component_key == 'Formula-State':
                        component_id_ = components[0].formula
                        column_id_ = 'Formula'
                    else:
                        raise Exception('Invalid component_key!')

                    # NOTE: build data
                    return self.build_data(
                        component_name=component_id_,
                        databook=databook,
                        table=table,
                        column_name=column_id_,
                        component_state=component_state_,
                    )
                elif tb_info_res_['Type'] == 'Matrix-Data':  # ! matrix-data
                    # check
                    if len(components) < 2:
                        raise Exception(
                            'At least two component names required!')

                    # set component names
                    component_names_ = [comp.name for comp in components]
                    # build matrix-data
                    return self.build_matrix_data(
                        component_names=component_names_,
                        databook=databook,
                        table=table
                    )
                else:
                    raise Exception('No data/equation found!')
            else:
                raise Exception('Table loading error!')
        except Exception as e:
            raise Exception(f'Building thermo property error {e}')

    def build_equation(
        self,
        component_name: str,
        databook: int | str,
        table: int | str,
        column_name: Optional[str | list[str]] = None,
        query: bool = False,
        component_state: Optional[str] = None,
    ) -> TableEquation:
        '''
        Build equation for as:
            step1: get thermo data for a component
            step2: get equation for the data (parameters)

        Parameters
        ----------
        component_name : str
            string of component name (e.g. 'Carbon dioxide')
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        column_name : str | list
            column name (e.g. 'Name') | list as ['Name','state']
        query : bool
            query to search a dataframe
        component_state : str, optional
            component state (e.g. 'g', 'l', 's')

        Returns
        -------
        eqs: TableEquation
            equation object
        '''
        try:
            # check search option
            if column_name is None:
                column_name = 'Name'

            # find databook zero-based id (real)
            db, db_name, db_rid = self.find_databook(databook)
            # databook id
            databook_id = db_rid + 1

            # find table zero-based id
            tb_id, tb_name = self.find_table(databook, table)
            # table id
            table_id = tb_id + 1

            # get data from api
            # ! dataframe and PayLoadType
            component_data = self.get_component_data(
                component_name=component_name,
                databook_id=databook_id,
                table_id=table_id,
                column_name=column_name,
                query=query,
                component_state=component_state
            )

            # check loading state
            if component_data is not None:
                # check availability
                if len(component_data) > 0:
                    # ! reset data
                    TransDataC = TransData(component_data)
                    # transform api data
                    TransDataC.trans()
                    # transformed api data
                    transform_api_data = TransDataC.data_trans
                    # check data type
                    _data_type = TransDataC.data_type

                    # ! check datatype compatibility
                    if _data_type != 'equation':
                        print("The selected table contains no data for building\
                            equation! check table id and try again.")

                        raise Exception('Building equation failed!')

                    # ! build equation
                    # check eq exists
                    eqs = self.equation_load(
                        databook_id, table_id)

                    # update trans_data
                    eqs.trans_data = transform_api_data

                    # equation init
                    eqs.eqSet()
                    # res
                    return eqs
                else:
                    raise Exception(
                        "Data for {} not available!".format(component_name))
            else:
                raise Exception("Building equation failed!")
        except Exception as e:
            raise Exception(f'Building equation error {e}')

    def build_data(
        self,
        component_name: str,
        databook: int | str,
        table: int | str,
        column_name: Optional[str | list[str]] = None,
        query: bool = False,
        component_state: Optional[str] = None,
    ) -> TableData:
        '''
        Build data as:
            step1: get thermo data for a component

        Parameters
        ----------
        component_name : str
            string of component name (e.g. 'Carbon dioxide')
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        column_name : str | list
            column name (e.g. 'Name') | list as ['Name','state']
        query : bool
            query to search a dataframe
        component_state : str, optional
            component state (e.g. 'g', 'l', 's')

        Returns
        -------
        TableData
            table data object
        '''
        try:
            # check search option
            if column_name is None:
                column_name = 'Name'

            # find databook zero-based id (real)
            db, db_name, db_rid = self.find_databook(databook)
            # databook id
            databook_id = db_rid + 1

            # find table zero-based id
            tb_id, tb_name = self.find_table(databook, table)
            # table id
            table_id = tb_id + 1

            # SECTION: get data from api
            # ! dataframe and PayLoadType
            component_data = self.get_component_data(
                component_name=component_name,
                databook_id=databook_id,
                table_id=table_id,
                column_name=column_name,
                query=query,
                component_state=component_state
            )

            # check loading state
            if component_data is not None:
                # check availability
                if len(component_data) > 0:
                    # ! trans data
                    TransDataC = TransData(component_data)
                    # transform api data
                    TransDataC.trans()
                    # transformed api data
                    transform_api_data = TransDataC.data_trans

                    # ! check data type
                    _data_type = TransDataC.data_type
                    if _data_type != 'data':
                        print(
                            "The selected table contains no data for building data!\
                            check table id and try again.")

                        raise Exception('Building data failed!')

                    # ! build data
                    # * construct template
                    # check eq exists
                    dts = self.data_load(
                        databook_id, table_id)

                    # ! check
                    if dts is not None:
                        # update trans_data
                        dts.trans_data = transform_api_data
                        # prop data
                        dts.prop_data = transform_api_data
                    else:
                        raise Exception('Building data failed!')

                    # res
                    return dts
                else:
                    raise Exception(
                        "Data for {} not available!".format(component_name))
            else:
                raise Exception("Building data failed!")
        except Exception as e:
            raise Exception(f'Building data error {e}')

    def build_matrix_equation(
        self,
        component_names: list[str],
        databook: int | str,
        table: int | str,
        column_name: Optional[str | list[str]] = None,
        query: bool = False
    ) -> TableMatrixEquation:
        '''
        Build matrix-equation for as:
            step1: get thermo data for a component
            step2: get equation for the data (parameters)

        Parameters
        ----------
        component_names : list[str]
            component name list (e.g. ['Methanol','Ethanol'])
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        column_name : str | list
            column name (e.g. 'Name') | list as ['Name','state']

        Returns
        -------
        eqs: TableMatrixEquation
            matrix-equation object
        '''
        try:
            # check search option
            if column_name is None:
                column_name = 'Name'

            # component no
            component_no = len(component_names)
            # check
            if component_no <= 1:
                raise Exception('At least two components are required')

            # find databook zero-based id (real)
            db, db_name, db_rid = self.find_databook(databook)
            # databook id
            databook_id = db_rid + 1

            # find table zero-based id
            tb_id, tb_name = self.find_table(databook, table)
            # table id
            table_id = tb_id + 1

            # SECTION: create matrix-data
            # ! retrieve all data from matrix-table (csv file)
            # matrix table
            matrix_table = self.table_data(databook, table)

            # NOTE
            # get data from api
            component_data_pack = []

            # looping through components
            for component_name in component_names:
                # component name
                component_name = str(component_name).strip()

                # get data from api
                component_data = self.get_component_data(
                    component_name,
                    databook_id,
                    table_id,
                    column_name=column_name,
                    query=query,
                    matrix_tb=True
                )
                # save
                component_data_pack.append({
                    'component_name': component_name,
                    'data': component_data
                })

            # SECTION
            # check loading state
            if component_data_pack:
                # check availability
                if len(component_data_pack) > 0:
                    # ! trans data
                    TransDataC = TransMatrixData(component_data_pack)
                    # transform api data
                    TransDataC.trans()
                    # transformed api data
                    transform_api_data = TransDataC.data_trans_pack
                    # check data type
                    _data_type = TransDataC.data_type

                    # ! check datatype compatibility
                    if _data_type != 'matrix-equations':
                        print("The selected table contains no data for building\
                            equation! check table id and try again.")

                        raise Exception('Building matrix-equation failed!')

                    # ! build equation
                    # ! reading yml reference
                    # check eq exists
                    eqs = self.matrix_equation_load(
                        databook_id, table_id)

                    # NOTE: update trans_data
                    eqs.trans_data_pack = transform_api_data
                    # NOTE: matrix table (data template)
                    eqs.matrix_table = matrix_table

                    # equation init
                    eqs.eqSet()
                    # res
                    return eqs
                else:
                    raise Exception("Data for {} not available!".format(
                        ",".join(component_names)))
            else:
                raise Exception("Building matrix-equation failed!")
        except Exception as e:
            raise Exception(f'Building matrix-equation error {e}')

    def build_matrix_data(
        self,
        component_names: list[str],
        databook: int | str,
        table: int | str,
        column_name: Optional[str | list[str]] = None,
        query: bool = False
    ) -> TableMatrixData:
        '''
        Build matrix data as:
            step1: get thermo matrix data

        Parameters
        ----------
        component_names : list[str]
            component name list (e.g. ['Methanol','Ethanol'])
        databook : int | str
            databook id or name
        table : int | str
            table id or name
        column_name : str | list
            column name (e.g. 'Name') | list as ['Name','state']

        Returns
        -------
        TableMatrixData
            matrix-data object
        '''
        try:
            # check component list
            if not isinstance(component_names, list):
                raise Exception('Component names must be a list')

            # check component name
            if not all(isinstance(name, str) for name in component_names):
                raise Exception('Component names must be strings')

            # check search option
            if column_name is None:
                column_name = 'Name'

            # find databook zero-based id (real)
            db, db_name, db_rid = self.find_databook(databook)
            # databook id
            databook_id = db_rid + 1

            # find table zero-based id
            tb_id, tb_name = self.find_table(databook, table)
            # table id
            table_id = tb_id + 1

            # NOTE: matrix table
            # ! retrieve all data from matrix-table
            # ? usually matrix-table data are limited
            matrix_table = self.table_data(databook, table)

            # SECTION: get data from api
            component_data_pack = []

            # looping through components
            for component_name in component_names:
                # get data
                component_data = self.get_component_data(
                    component_name.strip(),
                    databook_id,
                    table_id,
                    column_name=column_name,
                    query=query,
                    matrix_tb=True
                )
                # save
                component_data_pack.append({
                    'component_name': str(component_name).strip(),
                    'data': component_data
                })

            # check loading state
            if component_data_pack:
                # check availability
                if len(component_data_pack) > 0:
                    # ! trans data
                    TransMatrixDataC = TransMatrixData(component_data_pack)
                    # transform api data
                    TransMatrixDataC.trans()
                    # transformed api data
                    transform_api_data = TransMatrixDataC.data_trans_pack

                    # ! check data type
                    _data_type = TransMatrixDataC.data_type
                    if _data_type != 'matrix-data':
                        print(
                            "The selected table contains no data for building matrix-data! check table id and try again.")

                        raise Exception('Building data failed!')

                    # ! build data
                    # check eq exists
                    dts = self.matrix_data_load(
                        databook_id, table_id)

                    # ! check
                    if dts is not None:
                        # check type
                        if isinstance(dts, TableMatrixData):
                            if hasattr(dts, 'trans_data_pack') and hasattr(dts, 'prop_data_pack'):
                                # NOTE: update trans_data
                                dts.trans_data_pack = transform_api_data
                                # NOTE: prop data
                                dts.prop_data_pack = transform_api_data
                                # NOTE: matrix table
                                dts.matrix_table = matrix_table
                                # NOTE: matrix element
                                dts.matrix_elements = component_names

                                # res
                                return dts
                            else:
                                raise Exception('Building data failed!')
                        else:
                            raise Exception('Building data failed!')
                    else:
                        raise Exception('Building data failed!')
                else:
                    raise Exception("Data for {} not available!".format(
                        ', '.join(component_names)))
            else:
                raise Exception("Building data failed!")
        except Exception as e:
            raise Exception(f'Building matrix data error {e}')

    def __search_databook(
        self,
        search_terms: list[str],
        search_mode: str,
        column_names: list[str] = ['Name', 'Formula']
    ) -> list[dict[str, str]]:
        """
        Search a term through all databook for instance a component name

        Parameters
        ----------
        search_terms : list[str]
            search terms as list, e.g. ['Carbon dioxide','CO2']
        search_mode : Literal['exact', 'similar']
            search mode, 'exact' or 'similar'
        column_names : list[str]
            column names to search, e.g. ['Name', 'Formula']

        Returns
        -------
        list[dict[str, str]]
            search results as list of dictionaries, each dictionary contains
        """
        try:
            # set table reference
            # to load both internal and external data (csv files)
            TableReferenceC = TableReference(custom_ref=self.custom_ref)

            # search
            res = TableReferenceC.search_component(
                search_terms, search_mode, column_names=column_names)

            return res

        except Exception as e:
            raise Exception(f'Search databook error {e}')

    def search_databook(
            self,
            search_terms: list[str],
            column_names: list[str] = ['Name', 'Formula'],
            res_format: Literal[
                'list', 'dataframe', 'json', 'dict'
            ] = 'dict',
            search_mode: Literal[
                'exact', 'similar'
            ] = 'exact'
    ) -> ComponentSearch:
        """
        Search a term through all databook for instance a component name

        Parameters
        ----------
        search_terms : list[str]
            search terms as list, e.g. ['Carbon dioxide','CO2']
        column_names : list[str]
            column names to search, e.g. ['Name', 'Formula']
        res_format : Literal['list', 'dataframe', 'json', 'dict']
            result format, 'list', 'dataframe', 'json' or 'dict'
        search_mode : Literal['exact', 'similar']
            search mode, 'exact' or 'similar'

        Returns
        -------
        ComponentSearchResult
            search results
        """
        try:
            # call async function
            res = self.__search_databook(
                search_terms,
                search_mode,
                column_names
            )

            # check
            if len(res) == 0:
                logging.warning(
                    f'No results found for the search terms: {search_terms}, search mode: {search_mode}'
                )
                return []

            # dict
            res_dict = {f'record-{i+1}': item for i, item in enumerate(res)}

            res_dict = dict(
                {
                    'message': f'results found for the search terms : {search_terms}, search mode : {search_mode}'
                }, **res_dict
            )

            # NOTE: result settings
            # check res_format
            if res_format == 'list':
                return res
            elif res_format == 'dataframe':
                # dataframe
                return pd.DataFrame(res)
            elif res_format == 'json':
                # json
                return json.dumps(res_dict, indent=4)
            elif res_format == 'dict':
                return res_dict
            else:
                raise ValueError("Invalid res_format")
        except Exception as e:
            raise Exception(f'Search databook error {e}')

    def __list_components(self):
        """
        List all components in the databook
        """
        try:
            # set table reference
            # to load both internal and external data (csv files)
            TableReferenceC = TableReference(custom_ref=self.custom_ref)

            # search
            res = TableReferenceC.list_all_components()

            return res

        except Exception as e:
            raise Exception(f'Search databook error {e}')

    def list_components(
        self,
        res_format: Literal[
            'list', 'dict', 'json'
        ] = 'dict'
    ) -> ListComponents:
        """
        List all components in the databook

        Parameters
        ----------
        res_format : Literal['list', 'dict', 'json']
            result format, 'list', 'dict' or 'json'

        Returns
        -------
        ListComponents
            list of components in the databook
        """
        try:
            # exec
            res, _ = self.__list_components()

            # res dict
            res_dict = {
                'components': res
            }

            # json
            res_json = json.dumps(res_dict, indent=4)

            # check res_format
            if res_format == 'list':
                return res
            elif res_format == 'dict':
                return res_dict
            elif res_format == 'json':
                return res_json
            else:
                raise ValueError("Invalid res_format")

        except Exception as e:
            raise Exception(f'Listing component error {e}')

    def list_components_info(
            self,
            res_format: Literal[
                'list', 'dict', 'json'
            ] = 'dict'
    ) -> ListComponentsInfo:
        """
        List components information in the databook

        Parameters
        ----------
        res_format : Literal['list', 'dict', 'json']
            result format, 'list', 'dict' or 'json'

        Returns
        -------
        ListComponentsInfo
            list of components information in the databook
        """
        try:
            # from async
            _, res = self.__list_components()

            # dict
            res_dict = {f'record-{i+1}': item for i, item in enumerate(res)}
            # json
            res_json = json.dumps(res_dict, indent=4)

            # check res_format
            if res_format == 'list':
                return res
            elif res_format == 'dict':
                return res_dict
            elif res_format == 'json':
                return res_json
            else:
                raise ValueError("Invalid res_format")

        except Exception as e:
            raise Exception(f'Listing component info error {e}')

__list_components()

List all components in the databook

Source code in pyThermoDB/docs/thermo.py

def __list_components(self):
    """
    List all components in the databook
    """
    try:
        # set table reference
        # to load both internal and external data (csv files)
        TableReferenceC = TableReference(custom_ref=self.custom_ref)

        # search
        res = TableReferenceC.list_all_components()

        return res

    except Exception as e:
        raise Exception(f'Search databook error {e}')

__search_databook(search_terms, search_mode, column_names=['Name', 'Formula'])

Search a term through all databook for instance a component name

Parameters

search_terms : list[str] search terms as list, e.g. ['Carbon dioxide','CO2'] search_mode : Literal['exact', 'similar'] search mode, 'exact' or 'similar' column_names : list[str] column names to search, e.g. ['Name', 'Formula']

Returns

list[dict[str, str]] search results as list of dictionaries, each dictionary contains

Source code in pyThermoDB/docs/thermo.py

def __search_databook(
    self,
    search_terms: list[str],
    search_mode: str,
    column_names: list[str] = ['Name', 'Formula']
) -> list[dict[str, str]]:
    """
    Search a term through all databook for instance a component name

    Parameters
    ----------
    search_terms : list[str]
        search terms as list, e.g. ['Carbon dioxide','CO2']
    search_mode : Literal['exact', 'similar']
        search mode, 'exact' or 'similar'
    column_names : list[str]
        column names to search, e.g. ['Name', 'Formula']

    Returns
    -------
    list[dict[str, str]]
        search results as list of dictionaries, each dictionary contains
    """
    try:
        # set table reference
        # to load both internal and external data (csv files)
        TableReferenceC = TableReference(custom_ref=self.custom_ref)

        # search
        res = TableReferenceC.search_component(
            search_terms, search_mode, column_names=column_names)

        return res

    except Exception as e:
        raise Exception(f'Search databook error {e}')

build_components_thermo_property(components, databook, table, component_key='Name-State')

Build thermo property for a component including data, equation, matrix-data and matrix-equation.

Parameters

components : str string of component name (e.g. 'Carbon dioxide') component_state : str, optional component state (e.g. 'g', 'l', 's') databook : int | str databook id or name table : int | str table id or name component_key : Literal['Name-State', 'Formula-State'], optional The key to use for identifying the component, by default 'Name-State'.

Returns

ThermoProperty table object with data loaded - TableEquation - TableData - TableMatrixEquation - TableMatrixData

Notes

• Table should contain columns for 'Name', 'Formula', and 'State'. Otherwise an error will be raised.
• For 'Equation' and 'Data' types, only one component should be provided.
• For 'Matrix-Equation' and 'Matrix-Data' types, at least two components should be provided.
• The component_key parameter determines whether to use the component's name or formula along

Source code in pyThermoDB/docs/thermo.py

def build_components_thermo_property(
    self,
    components: List[Component],
    databook: int | str,
    table: int | str,
    component_key: Literal[
        'Name-State', 'Formula-State'
    ] = 'Name-State',
) -> ThermoProperty:
    '''
    Build thermo property for a component including data, equation, matrix-data and matrix-equation.

    Parameters
    ----------
    components : str
        string of component name (e.g. 'Carbon dioxide')
    component_state : str, optional
        component state (e.g. 'g', 'l', 's')
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    component_key : Literal['Name-State', 'Formula-State'], optional
        The key to use for identifying the component, by default 'Name-State'.

    Returns
    -------
    ThermoProperty
        table object with data loaded
        - TableEquation
        - TableData
        - TableMatrixEquation
        - TableMatrixData

    Notes
    -----
    - Table should contain columns for 'Name', 'Formula', and 'State'. Otherwise an error will be raised.
    - For 'Equation' and 'Data' types, only one component should be provided.
    - For 'Matrix-Equation' and 'Matrix-Data' types, at least two components should be provided.
    - The `component_key` parameter determines whether to use the component's name or formula along
    '''
    try:
        # NOTE: detect table type
        tb_info_res_ = self.table_info(databook, table, res_format='dict')

        # SECTION: build thermo property
        if isinstance(tb_info_res_, dict):
            # check
            if tb_info_res_['Type'] == 'Equation':  # ! equation

                # NOTE: check components
                if len(components) != 1:
                    raise Exception('Only one component required!')

                if not isinstance(components[0], Component):
                    raise Exception('Invalid component!')

                # set component id
                component_id_ = None
                component_state_ = components[0].state
                column_id_ = None

                # NOTE: set component id and column id
                if component_key == 'Name-State':
                    component_id_ = components[0].name
                    column_id_ = 'Name'
                elif component_key == 'Formula-State':
                    component_id_ = components[0].formula
                    column_id_ = 'Formula'
                else:
                    raise Exception('Invalid component_key!')

                # NOTE: build equation
                return self.build_equation(
                    component_name=component_id_,
                    databook=databook,
                    table=table,
                    column_name=column_id_,
                    component_state=component_state_,
                )
            elif tb_info_res_['Type'] == 'Data':  # ! data
                # check
                if len(components) > 1:
                    raise Exception('Only one component name required!')

                if not isinstance(components[0], Component):
                    raise Exception('Invalid component!')

                # NOTE: set component id
                component_id_ = None
                component_state_ = components[0].state
                column_id_ = None

                # NOTE: set component id and column id
                if component_key == 'Name-State':
                    component_id_ = components[0].name
                    column_id_ = 'Name'
                elif component_key == 'Formula-State':
                    component_id_ = components[0].formula
                    column_id_ = 'Formula'
                else:
                    raise Exception('Invalid component_key!')

                # NOTE: build data
                return self.build_data(
                    component_name=component_id_,
                    databook=databook,
                    table=table,
                    column_name=column_id_,
                    component_state=component_state_,
                )
            elif tb_info_res_['Type'] == 'Matrix-Data':  # ! matrix-data
                # check
                if len(components) < 2:
                    raise Exception(
                        'At least two component names required!')

                # set component names
                component_names_ = [comp.name for comp in components]
                # build matrix-data
                return self.build_matrix_data(
                    component_names=component_names_,
                    databook=databook,
                    table=table
                )
            else:
                raise Exception('No data/equation found!')
        else:
            raise Exception('Table loading error!')
    except Exception as e:
        raise Exception(f'Building thermo property error {e}')

build_data(component_name, databook, table, column_name=None, query=False, component_state=None)

Build data as

step1: get thermo data for a component

Parameters

component_name : str string of component name (e.g. 'Carbon dioxide') databook : int | str databook id or name table : int | str table id or name column_name : str | list column name (e.g. 'Name') | list as ['Name','state'] query : bool query to search a dataframe component_state : str, optional component state (e.g. 'g', 'l', 's')

Returns

TableData table data object

Source code in pyThermoDB/docs/thermo.py

def build_data(
    self,
    component_name: str,
    databook: int | str,
    table: int | str,
    column_name: Optional[str | list[str]] = None,
    query: bool = False,
    component_state: Optional[str] = None,
) -> TableData:
    '''
    Build data as:
        step1: get thermo data for a component

    Parameters
    ----------
    component_name : str
        string of component name (e.g. 'Carbon dioxide')
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    column_name : str | list
        column name (e.g. 'Name') | list as ['Name','state']
    query : bool
        query to search a dataframe
    component_state : str, optional
        component state (e.g. 'g', 'l', 's')

    Returns
    -------
    TableData
        table data object
    '''
    try:
        # check search option
        if column_name is None:
            column_name = 'Name'

        # find databook zero-based id (real)
        db, db_name, db_rid = self.find_databook(databook)
        # databook id
        databook_id = db_rid + 1

        # find table zero-based id
        tb_id, tb_name = self.find_table(databook, table)
        # table id
        table_id = tb_id + 1

        # SECTION: get data from api
        # ! dataframe and PayLoadType
        component_data = self.get_component_data(
            component_name=component_name,
            databook_id=databook_id,
            table_id=table_id,
            column_name=column_name,
            query=query,
            component_state=component_state
        )

        # check loading state
        if component_data is not None:
            # check availability
            if len(component_data) > 0:
                # ! trans data
                TransDataC = TransData(component_data)
                # transform api data
                TransDataC.trans()
                # transformed api data
                transform_api_data = TransDataC.data_trans

                # ! check data type
                _data_type = TransDataC.data_type
                if _data_type != 'data':
                    print(
                        "The selected table contains no data for building data!\
                        check table id and try again.")

                    raise Exception('Building data failed!')

                # ! build data
                # * construct template
                # check eq exists
                dts = self.data_load(
                    databook_id, table_id)

                # ! check
                if dts is not None:
                    # update trans_data
                    dts.trans_data = transform_api_data
                    # prop data
                    dts.prop_data = transform_api_data
                else:
                    raise Exception('Building data failed!')

                # res
                return dts
            else:
                raise Exception(
                    "Data for {} not available!".format(component_name))
        else:
            raise Exception("Building data failed!")
    except Exception as e:
        raise Exception(f'Building data error {e}')

build_equation(component_name, databook, table, column_name=None, query=False, component_state=None)

Build equation for as

step1: get thermo data for a component step2: get equation for the data (parameters)

Parameters

component_name : str string of component name (e.g. 'Carbon dioxide') databook : int | str databook id or name table : int | str table id or name column_name : str | list column name (e.g. 'Name') | list as ['Name','state'] query : bool query to search a dataframe component_state : str, optional component state (e.g. 'g', 'l', 's')

Returns

eqs: TableEquation equation object

Source code in pyThermoDB/docs/thermo.py

def build_equation(
    self,
    component_name: str,
    databook: int | str,
    table: int | str,
    column_name: Optional[str | list[str]] = None,
    query: bool = False,
    component_state: Optional[str] = None,
) -> TableEquation:
    '''
    Build equation for as:
        step1: get thermo data for a component
        step2: get equation for the data (parameters)

    Parameters
    ----------
    component_name : str
        string of component name (e.g. 'Carbon dioxide')
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    column_name : str | list
        column name (e.g. 'Name') | list as ['Name','state']
    query : bool
        query to search a dataframe
    component_state : str, optional
        component state (e.g. 'g', 'l', 's')

    Returns
    -------
    eqs: TableEquation
        equation object
    '''
    try:
        # check search option
        if column_name is None:
            column_name = 'Name'

        # find databook zero-based id (real)
        db, db_name, db_rid = self.find_databook(databook)
        # databook id
        databook_id = db_rid + 1

        # find table zero-based id
        tb_id, tb_name = self.find_table(databook, table)
        # table id
        table_id = tb_id + 1

        # get data from api
        # ! dataframe and PayLoadType
        component_data = self.get_component_data(
            component_name=component_name,
            databook_id=databook_id,
            table_id=table_id,
            column_name=column_name,
            query=query,
            component_state=component_state
        )

        # check loading state
        if component_data is not None:
            # check availability
            if len(component_data) > 0:
                # ! reset data
                TransDataC = TransData(component_data)
                # transform api data
                TransDataC.trans()
                # transformed api data
                transform_api_data = TransDataC.data_trans
                # check data type
                _data_type = TransDataC.data_type

                # ! check datatype compatibility
                if _data_type != 'equation':
                    print("The selected table contains no data for building\
                        equation! check table id and try again.")

                    raise Exception('Building equation failed!')

                # ! build equation
                # check eq exists
                eqs = self.equation_load(
                    databook_id, table_id)

                # update trans_data
                eqs.trans_data = transform_api_data

                # equation init
                eqs.eqSet()
                # res
                return eqs
            else:
                raise Exception(
                    "Data for {} not available!".format(component_name))
        else:
            raise Exception("Building equation failed!")
    except Exception as e:
        raise Exception(f'Building equation error {e}')

build_matrix_data(component_names, databook, table, column_name=None, query=False)

Build matrix data as

step1: get thermo matrix data

Parameters

component_names : list[str] component name list (e.g. ['Methanol','Ethanol']) databook : int | str databook id or name table : int | str table id or name column_name : str | list column name (e.g. 'Name') | list as ['Name','state']

Returns

TableMatrixData matrix-data object

Source code in pyThermoDB/docs/thermo.py

def build_matrix_data(
    self,
    component_names: list[str],
    databook: int | str,
    table: int | str,
    column_name: Optional[str | list[str]] = None,
    query: bool = False
) -> TableMatrixData:
    '''
    Build matrix data as:
        step1: get thermo matrix data

    Parameters
    ----------
    component_names : list[str]
        component name list (e.g. ['Methanol','Ethanol'])
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    column_name : str | list
        column name (e.g. 'Name') | list as ['Name','state']

    Returns
    -------
    TableMatrixData
        matrix-data object
    '''
    try:
        # check component list
        if not isinstance(component_names, list):
            raise Exception('Component names must be a list')

        # check component name
        if not all(isinstance(name, str) for name in component_names):
            raise Exception('Component names must be strings')

        # check search option
        if column_name is None:
            column_name = 'Name'

        # find databook zero-based id (real)
        db, db_name, db_rid = self.find_databook(databook)
        # databook id
        databook_id = db_rid + 1

        # find table zero-based id
        tb_id, tb_name = self.find_table(databook, table)
        # table id
        table_id = tb_id + 1

        # NOTE: matrix table
        # ! retrieve all data from matrix-table
        # ? usually matrix-table data are limited
        matrix_table = self.table_data(databook, table)

        # SECTION: get data from api
        component_data_pack = []

        # looping through components
        for component_name in component_names:
            # get data
            component_data = self.get_component_data(
                component_name.strip(),
                databook_id,
                table_id,
                column_name=column_name,
                query=query,
                matrix_tb=True
            )
            # save
            component_data_pack.append({
                'component_name': str(component_name).strip(),
                'data': component_data
            })

        # check loading state
        if component_data_pack:
            # check availability
            if len(component_data_pack) > 0:
                # ! trans data
                TransMatrixDataC = TransMatrixData(component_data_pack)
                # transform api data
                TransMatrixDataC.trans()
                # transformed api data
                transform_api_data = TransMatrixDataC.data_trans_pack

                # ! check data type
                _data_type = TransMatrixDataC.data_type
                if _data_type != 'matrix-data':
                    print(
                        "The selected table contains no data for building matrix-data! check table id and try again.")

                    raise Exception('Building data failed!')

                # ! build data
                # check eq exists
                dts = self.matrix_data_load(
                    databook_id, table_id)

                # ! check
                if dts is not None:
                    # check type
                    if isinstance(dts, TableMatrixData):
                        if hasattr(dts, 'trans_data_pack') and hasattr(dts, 'prop_data_pack'):
                            # NOTE: update trans_data
                            dts.trans_data_pack = transform_api_data
                            # NOTE: prop data
                            dts.prop_data_pack = transform_api_data
                            # NOTE: matrix table
                            dts.matrix_table = matrix_table
                            # NOTE: matrix element
                            dts.matrix_elements = component_names

                            # res
                            return dts
                        else:
                            raise Exception('Building data failed!')
                    else:
                        raise Exception('Building data failed!')
                else:
                    raise Exception('Building data failed!')
            else:
                raise Exception("Data for {} not available!".format(
                    ', '.join(component_names)))
        else:
            raise Exception("Building data failed!")
    except Exception as e:
        raise Exception(f'Building matrix data error {e}')

build_matrix_equation(component_names, databook, table, column_name=None, query=False)

Build matrix-equation for as

step1: get thermo data for a component step2: get equation for the data (parameters)

Parameters

component_names : list[str] component name list (e.g. ['Methanol','Ethanol']) databook : int | str databook id or name table : int | str table id or name column_name : str | list column name (e.g. 'Name') | list as ['Name','state']

Returns

eqs: TableMatrixEquation matrix-equation object

Source code in pyThermoDB/docs/thermo.py

def build_matrix_equation(
    self,
    component_names: list[str],
    databook: int | str,
    table: int | str,
    column_name: Optional[str | list[str]] = None,
    query: bool = False
) -> TableMatrixEquation:
    '''
    Build matrix-equation for as:
        step1: get thermo data for a component
        step2: get equation for the data (parameters)

    Parameters
    ----------
    component_names : list[str]
        component name list (e.g. ['Methanol','Ethanol'])
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    column_name : str | list
        column name (e.g. 'Name') | list as ['Name','state']

    Returns
    -------
    eqs: TableMatrixEquation
        matrix-equation object
    '''
    try:
        # check search option
        if column_name is None:
            column_name = 'Name'

        # component no
        component_no = len(component_names)
        # check
        if component_no <= 1:
            raise Exception('At least two components are required')

        # find databook zero-based id (real)
        db, db_name, db_rid = self.find_databook(databook)
        # databook id
        databook_id = db_rid + 1

        # find table zero-based id
        tb_id, tb_name = self.find_table(databook, table)
        # table id
        table_id = tb_id + 1

        # SECTION: create matrix-data
        # ! retrieve all data from matrix-table (csv file)
        # matrix table
        matrix_table = self.table_data(databook, table)

        # NOTE
        # get data from api
        component_data_pack = []

        # looping through components
        for component_name in component_names:
            # component name
            component_name = str(component_name).strip()

            # get data from api
            component_data = self.get_component_data(
                component_name,
                databook_id,
                table_id,
                column_name=column_name,
                query=query,
                matrix_tb=True
            )
            # save
            component_data_pack.append({
                'component_name': component_name,
                'data': component_data
            })

        # SECTION
        # check loading state
        if component_data_pack:
            # check availability
            if len(component_data_pack) > 0:
                # ! trans data
                TransDataC = TransMatrixData(component_data_pack)
                # transform api data
                TransDataC.trans()
                # transformed api data
                transform_api_data = TransDataC.data_trans_pack
                # check data type
                _data_type = TransDataC.data_type

                # ! check datatype compatibility
                if _data_type != 'matrix-equations':
                    print("The selected table contains no data for building\
                        equation! check table id and try again.")

                    raise Exception('Building matrix-equation failed!')

                # ! build equation
                # ! reading yml reference
                # check eq exists
                eqs = self.matrix_equation_load(
                    databook_id, table_id)

                # NOTE: update trans_data
                eqs.trans_data_pack = transform_api_data
                # NOTE: matrix table (data template)
                eqs.matrix_table = matrix_table

                # equation init
                eqs.eqSet()
                # res
                return eqs
            else:
                raise Exception("Data for {} not available!".format(
                    ",".join(component_names)))
        else:
            raise Exception("Building matrix-equation failed!")
    except Exception as e:
        raise Exception(f'Building matrix-equation error {e}')

build_thermo_property(component_names, databook, table, **kwargs)

Build a thermodynamic property including data, equation, matrix-data and matrix-equation.

Parameters

component_names : list[str] list of component name (e.g. 'Carbon dioxide') databook : int | str databook id or name table : int | str table id or name **kwargs Additional keyword arguments to pass to the specific build methods. - component_state : str, optional component state (e.g. 'g', 'l', 's')

Returns

ThermoProperty table object with data loaded - TableEquation - TableData - TableMatrixEquation - TableMatrixData

Source code in pyThermoDB/docs/thermo.py

def build_thermo_property(
    self,
    component_names: list[str],
    databook: int | str,
    table: int | str,
    **kwargs
) -> ThermoProperty:
    """
    Build a thermodynamic property including data, equation, matrix-data and matrix-equation.

    Parameters
    ----------
    component_names :  list[str]
        list of component name (e.g. 'Carbon dioxide')
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    **kwargs
        Additional keyword arguments to pass to the specific build methods.
        - component_state : str, optional
            component state (e.g. 'g', 'l', 's')

    Returns
    -------
    ThermoProperty
        table object with data loaded
        - TableEquation
        - TableData
        - TableMatrixEquation
        - TableMatrixData
    """
    try:
        # SECTION: extract kwargs
        # LINK: column name
        column_name = kwargs.get('column_name', None)
        # LINK: query
        query = kwargs.get('query', False)

        # SECTION: detect table type
        tb_info_res_ = self.table_info(databook, table, res_format='dict')

        # SECTION: build thermo property
        if isinstance(tb_info_res_, dict):
            # check
            if tb_info_res_['Type'] == 'Equation':  # ! equation
                # check
                if len(component_names) > 1:
                    raise Exception('Only one component name required!')

                # component name set
                component_name_ = component_names[0]

                # build equation
                return self.build_equation(
                    component_name=component_name_,
                    databook=databook,
                    table=table,
                    column_name=column_name,
                )
            elif tb_info_res_['Type'] == 'Data':  # ! data
                # check
                if len(component_names) > 1:
                    raise Exception('Only one component name required!')

                # component name set
                component_name_ = component_names[0]

                # build data
                return self.build_data(
                    component_name=component_name_,
                    databook=databook,
                    table=table,
                    column_name=column_name,
                )
            elif tb_info_res_['Type'] == 'Matrix-Equation':  # ! matrix-equation
                # check
                if len(component_names) < 2:
                    raise Exception(
                        'At least two component names required!')
                # build matrix-equation
                return self.build_matrix_equation(
                    component_names,
                    databook,
                    table
                )
            elif tb_info_res_['Type'] == 'Matrix-Data':  # ! matrix-data
                # check
                if len(component_names) < 2:
                    raise Exception(
                        'At least two component names required!')
                # build matrix-data
                return self.build_matrix_data(
                    component_names,
                    databook,
                    table
                )
            else:
                raise Exception('No data/equation found!')
        else:
            raise Exception('Table loading error!')
    except Exception as e:
        raise Exception(f'Building thermo property error {e}')

check_component(component_name, databook, table, column_name=None, query=False, res_format='json')

Check a component availability in the selected databook and table

Parameters

component_name : str | list string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g'] databook : int | str databook id or name table : int | str table id or name column_name : str | list column name (e.g. 'Name') | list as ['Name','state'] query : str query to search a dataframe

Returns

str | dict[str, str] summary of the component availability

Source code in pyThermoDB/docs/thermo.py

def check_component(
        self,
        component_name: str | list[str],
        databook: int | str,
        table: int | str,
        column_name: Optional[str | list[str]] = None,
        query: bool = False,
        res_format: Literal[
            'dict', 'json', 'str'
        ] = 'json'
) -> Union[str, dict[str, str]]:
    '''
    Check a component availability in the selected databook and table

    Parameters
    ----------
    component_name : str | list
        string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g']
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    column_name : str | list
        column name (e.g. 'Name') | list as ['Name','state']
    query : str
        query to search a dataframe

    Returns
    -------
    str | dict[str, str]
        summary of the component availability
    '''
    try:
        # NOTE: check search option
        if column_name is None:
            column_name = 'Name'

        # NOTE: check
        if query:
            column_name = column_name

        # SECTION: find ids
        # find databook zero-based id (real)
        db, db_name, db_rid = self.find_databook(databook)
        # databook id (non-zero-based id)
        databook_id = db_rid + 1

        # find table zero-based id
        tb_id, tb_name = self.find_table(databook, table)
        # table id (non-zero-based id)
        table_id = tb_id + 1

        # res
        res = False

        # check databook_id and table_id are number or not
        if isNumber(databook_id) and isNumber(table_id):
            # check
            if self.data_source == 'api':
                # res = self.check_component_api(
                #     component_name, databook_id, table_id)
                pass
            elif self.data_source == 'local':
                res = self.check_component_local(
                    component_name=component_name,
                    databook_id=databook_id,
                    table_id=table_id,
                    column_name=column_name,
                    query=query
                )
            else:
                raise Exception('Data source error!')
        else:
            raise Exception("databook and table id required!")

        # res
        res_dict = {
            'databook_id': databook_id,
            'databook_name': db_name,
            'table_id': table_id,
            'table_name': tb_name,
            'component_name': component_name,
            'availability': res
        }

        # json
        res_json = json.dumps(res_dict, indent=4)

        # check
        if res_format == 'json':
            return res_json
        elif res_format == 'dict':
            return res_dict
        elif res_format == 'str':
            return res_json
        else:
            raise ValueError('Invalid res_format')
    except Exception as e:
        raise Exception(f"Component check error! {e}")

check_component_api(component_name, databook_id, table_id)

Check component availability in the selected databook and table

Parameters

component_name : str | list string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g'] databook_id : int databook id table_id : int table id column_name : str | list column name (e.g. 'Name') | list as ['Name','state']

Returns

comp_info : str component information

Source code in pyThermoDB/docs/thermo.py

def check_component_api(
        self,
        component_name: str | list,
        databook_id: int,
        table_id: int):
    '''
    Check component availability in the selected databook and table

    Parameters
    ----------
    component_name : str | list
        string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g']
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str | list
        column name (e.g. 'Name') | list as ['Name','state']

    Returns
    -------
    comp_info : str
        component information
    '''
    try:
        # check databook_id and table_id are number or not
        if isNumber(databook_id) and isNumber(table_id):
            # set api
            ManageC = Manage(API_URL, databook_id, table_id)
            # search
            compList = ManageC.component_list()
            # check availability
            # uppercase list
            compListUpper = uppercaseStringList(compList)
            if len(compList) > 0:
                # get databook
                databook_name = self.list_databooks(res_format='list')[
                    databook_id-1]
                # get table
                # table_name = self.list_tables(databook=databook_id, res_format='list')[
                #     table_id-1][0]

                list_tables_ = self.list_tables(
                    databook=databook_id,
                    res_format='list'
                )

                # set
                table_id_ = table_id - 1

                # check
                if len(list_tables_) > 0:
                    # get table name

                    table_name = "Obsolete Table"

                # check
                # if component_name.upper() in compListUpper:
                #     print(
                #         f"[{component_name}] available in [{table_name}] | [{databook_name}]")
                # else:
                #     print(f"{component_name} is not available.")
            else:
                print("API error. Please try again later.")

            return None
        else:
            raise Exception(
                "Invalid input. Please check the input type (databook_id and table_id).")
    except Exception as e:
        raise Exception(f'Checking data error {e}')

check_component_local(component_name, databook_id, table_id, column_name, query=False, verbose=False)

Check component availability in the selected databook and table

Parameters

component_name : str | list string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g'] databook_id : int databook id table_id : int table id column_name : str column name (e.g. 'Name') | list query : str query string (e.g. 'Name == "Carbon dioxide"')

Returns

object : bool component information

Notes

• Return True if df is not empty
• Return False if df is empty

Source code in pyThermoDB/docs/thermo.py

def check_component_local(
    self,
    component_name: str | list,
    databook_id: int,
    table_id: int,
    column_name: str | list[str],
    query: bool = False,
    verbose: bool = False
) -> bool:
    '''
    Check component availability in the selected databook and table

    Parameters
    ----------
    component_name : str | list
        string of component name (e.g. 'Carbon dioxide') | list as ['Carbon dioxide','g']
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str
        column name (e.g. 'Name') | list
    query : str
        query string (e.g. 'Name == "Carbon dioxide"')

    Returns
    -------
    object : bool
        component information

    Notes
    -----
    - Return True if df is not empty
    - Return False if df is empty
    '''
    try:
        # check databook_id and table_id are number or not
        if (
            isNumber(databook_id) and
            isNumber(table_id)
        ):
            # set api
            TableReferenceC = TableReference(custom_ref=self.custom_ref)

            # NOTE: search
            df = TableReferenceC.search_tables(
                databook_id=databook_id,
                table_id=table_id,
                column_name=column_name,
                lookup=component_name,  # ! exact match
                query=query
            )

            # NOTE: check availability
            if len(df) > 0:
                if verbose:
                    print(
                        f"[{component_name}] available in [{table_id}] | [{databook_id}]"
                    )

                # res
                return True
            else:
                # log
                if verbose:
                    print(f"{component_name} is not available.")

                # res
                return False
        else:
            logger.error(
                "Invalid input. Please check the input type (databook_id and table_id).")
            return False
    except Exception as e:
        logger.error(f'Checking data error {e}')
        return False

data_load(databook, table)

Display table header columns and other info

Parameters

databook : int | str databook id or name table : str table name

Returns

object : TableData table object with data loaded

Source code in pyThermoDB/docs/thermo.py

def data_load(
    self,
    databook: int | str,
    table: int | str
) -> TableData:
    '''
    Display table header columns and other info

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : str
        table name

    Returns
    -------
    object : TableData
        table object with data loaded
    '''
    try:
        # table type
        tb_type = ''
        # table name
        table_name = ''
        # table data
        table_data = []
        # databook id | name
        db, db_name, db_id = self.find_databook(databook)
        # get the tb
        tb = self.select_table(databook, table)

        # check
        if tb:
            # NOTE: table name
            table_name = tb['table']

            # NOTE: check data/equations
            if tb['data'] is None or tb['data'] == 'None':
                raise Exception(
                    'This method not compatible with the selected table!')

            tb_type = TableTypes.DATA.value

            # NOTE: check table values
            if tb['table_values'] is not None and tb['table_values'] != 'None':
                table_values = tb['table_values']
            else:
                table_values = None

            # NOTE: check table structure
            if tb['table_structure'] is not None and tb['table_structure'] != 'None':
                table_structure = tb['table_structure']
            else:
                table_structure = None

            # check data
            if tb_type == 'data':
                table_data = tb['data']

                # check
                if not isinstance(table_data, dict):
                    raise ValueError("Table data is not a dictionary!")

                # extract table data
                COLUMNS = table_data.get('COLUMNS')
                SYMBOL = table_data.get('SYMBOL')
                UNIT = table_data.get('UNIT')
                CONVERSION = table_data.get('CONVERSION')

                # NOTE: check if the table data is empty
                if not COLUMNS or not SYMBOL or not UNIT or not CONVERSION:
                    raise ValueError("Table data is empty!")

                # data no
                return TableData(
                    db_name,
                    table_name,
                    table_data,
                    table_values=table_values,
                    table_structure=table_structure
                )
            else:
                raise Exception('Table loading error!')
        else:
            raise Exception('Table loading error!')
    except Exception as e:
        raise Exception(f"Table loading error {e}")

databook_info(databook, res_format='json')

Get information about a databook.

Parameters

databook : int | str databook id or name res_format : Literal['dict', 'json'] Format of the returned data. Defaults to 'dict'.

Returns

res : Dict[str, str | Dict[str, str]] | str Dictionary containing databook information or a string representation. - 'DATABOOK-ID': ID of the databook. - 'DATABOOK-NAME': Name of the databook. - 'DESCRIPTION': Description of the databook.

Source code in pyThermoDB/docs/thermo.py

def databook_info(
    self,
    databook: int | str,
    res_format: Literal[
        'dict', 'str', 'json'
    ] = 'json'
) -> Dict[str, str | Dict[str, str]] | str:
    '''
    Get information about a databook.

    Parameters
    ----------
    databook : int | str
        databook id or name
    res_format : Literal['dict', 'json']
        Format of the returned data. Defaults to 'dict'.

    Returns
    -------
    res : Dict[str, str | Dict[str, str]] | str
        Dictionary containing databook information or a string representation.
        - 'DATABOOK-ID': ID of the databook.
        - 'DATABOOK-NAME': Name of the databook.
        - 'DESCRIPTION': Description of the databook.
    '''
    try:
        # find databook
        db, db_name, db_id = self.find_databook(databook)

        # get databook info
        res = self.get_descriptions_by_databook(db_name)

        # check
        if res_format == 'dict':
            return res
        elif res_format == 'str':
            # convert to json
            return str(res)
        elif res_format == 'json':
            # convert to json
            return json.dumps(res, indent=4)
        else:
            logging.error('Invalid res_format')

        return res
    except Exception as e:
        raise Exception(f"Databook info loading error! {e}")

equation_load(databook, table)

Display table header columns and other info

Parameters

databook : int | str databook id or name table : str table name

Returns

object: TableEquation

Notes

1. table should be a string

Source code in pyThermoDB/docs/thermo.py

def equation_load(
    self,
    databook: int | str,
    table: int | str
) -> TableEquation:
    '''
    Display table header columns and other info

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : str
        table name

    Returns
    -------
    object: TableEquation

    Notes
    -----
    1. table should be a string
    '''
    try:
        # table type
        # tb_type = ''
        # table name
        table_name = ''
        # table equations
        table_equations = []
        # databook id | name
        db, db_name, db_id = self.find_databook(databook)
        # get the tb
        tb = self.select_table(databook, table)

        # check
        if tb:
            # NOTE: table name
            table_name = tb['table']

            # NOTE: table type
            if tb['table_type'] is not None and tb['table_type'] != 'None':
                tb_type = TableTypes.EQUATIONS.value

            # NOTE: table values
            if tb['table_values'] is not None and tb['table_values'] != 'None':
                table_values = tb['table_values']
            else:
                table_values = None

            # NOTE: table structure
            if tb['table_structure'] is not None and tb['table_structure'] != 'None':
                table_structure = tb['table_structure']
            else:
                table_structure = None

            # check data/equations
            if tb['equations'] is not None and tb['equations'] != 'None':
                # set table type
                # tb_type = 'equation'

                # looping through equations
                for item in tb['equations']:
                    table_equations.append(item)

                # create table equation
                return TableEquation(
                    db_name,
                    table_name,
                    table_equations,
                    table_values=table_values,
                    table_structure=table_structure
                )
            else:
                raise Exception('Table loading error!')
        else:
            raise Exception('Table loading error!')

    except Exception as e:
        raise Exception(f"Table loading error {e}")

get_component_data(component_name, databook_id, table_id, column_name=None, dataframe=False, query=False, matrix_tb=False, component_state=None)

Get component data from database (api|local csvs)

Parameters

component_name : str string of component name (e.g. 'Carbon dioxide') databook_id : int databook id table_id : int table id column_name : str | list, optional column name dataframe : bool return dataframe or not query : bool query or not matrix_tb : bool matrix table or not component_state : str, optional component state (e.g. 'g', 'l', 's')

Returns

component_data : object | pandas dataframe component data

Source code in pyThermoDB/docs/thermo.py

def get_component_data(
    self,
    component_name: str,
    databook_id: int,
    table_id: int,
    column_name: Optional[str | list[str]] = None,
    dataframe: bool = False,
    query: bool = False,
    matrix_tb: bool = False,
    component_state: Optional[str] = None
):
    '''
    Get component data from database (api|local csvs)

    Parameters
    ----------
    component_name : str
        string of component name (e.g. 'Carbon dioxide')
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str | list, optional
        column name
    dataframe : bool
        return dataframe or not
    query : bool
        query or not
    matrix_tb : bool
        matrix table or not
    component_state : str, optional
        component state (e.g. 'g', 'l', 's')

    Returns
    -------
    component_data : object | pandas dataframe
        component data
    '''
    try:
        # check search option
        if column_name is None:
            column_name = 'Name'

        # set
        component_name = str(component_name).strip()
        # check datasource
        if self.data_source == 'api':
            # component_data = self.get_component_data_api(
            #     component_name, databook_id, table_id, column_name,
            #     dataframe=dataframe)
            return None
        elif self.data_source == 'local':
            component_data = self.get_component_data_local(
                component_name=component_name,
                databook_id=databook_id,
                table_id=table_id,
                column_name=column_name,
                component_state=component_state,
                dataframe=dataframe,
                query=query,
                matrix_tb=matrix_tb
            )
        else:
            raise Exception('Data source error!')
        # res
        return component_data
    except Exception as e:
        raise Exception(f"Loading data failed {e}")

get_component_data_api(component_name, databook_id, table_id, dataframe=False)

Get component data from database (api)

It consists of

step1: get thermo data for a component, step2: get equation for the data (parameters).

Parameters

component_name : str string of component name (e.g. 'Carbon dioxide') databook_id : int databook id table_id : int table id column_name : str column name dataframe : bool return dataframe or not

Returns

component_data : object | pandas dataframe component data

Source code in pyThermoDB/docs/thermo.py

def get_component_data_api(
        self,
        component_name: str,
        databook_id: int,
        table_id: int,
        dataframe: bool = False
):
    '''
    Get component data from database (api)

    It consists of:
        step1: get thermo data for a component,
        step2: get equation for the data (parameters).

    Parameters
    ----------
    component_name : str
        string of component name (e.g. 'Carbon dioxide')
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str
        column name
    dataframe : bool
        return dataframe or not

    Returns
    -------
    component_data : object | pandas dataframe
        component data
    '''
    # set api
    ManageC = Manage(API_URL, databook_id, table_id)
    # search
    component_data = ManageC.component_info(component_name)
    # check availability
    if len(component_data) > 0:
        # check
        if dataframe:
            df = pd.DataFrame(component_data, columns=[
                'header', 'symbol', 'records', 'unit'])
            return df
        else:
            return component_data
    else:
        print(f"Data for {component_name} not available!")
        return {}

get_component_data_local(component_name, databook_id, table_id, column_name, component_state=None, dataframe=False, query=False, matrix_tb=False)

Get component data from database (local csv files)

Parameters

component_name : str string of component name (e.g. 'Carbon dioxide') databook_id : int databook id table_id : int table id column_name : str column name | query to find a record from a dataframe component_state : str, optional component state (e.g. 'g', 'l', 's') dataframe : bool return dataframe or not query : bool query or not matrix_tb : bool matrix table or not

Returns

payload : dict | pandas dataframe component information

Source code in pyThermoDB/docs/thermo.py

def get_component_data_local(
    self,
    component_name: str,
    databook_id: int,
    table_id: int,
    column_name: str | list[str],
    component_state: Optional[str] = None,
    dataframe: bool = False,
    query: bool = False,
    matrix_tb: bool = False
):
    '''
    Get component data from database (local csv files)

    Parameters
    ----------
    component_name : str
        string of component name (e.g. 'Carbon dioxide')
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str
        column name | query to find a record from a dataframe
    component_state : str, optional
        component state (e.g. 'g', 'l', 's')
    dataframe : bool
        return dataframe or not
    query : bool
        query or not
    matrix_tb : bool
        matrix table or not

    Returns
    -------
    payload : dict | pandas dataframe
        component information
    '''
    try:
        # check databook_id and table_id are number or not
        if isNumber(databook_id) and isNumber(table_id):
            # set api
            TableReferenceC = TableReference(custom_ref=self.custom_ref)

            # NOTE: set query
            if component_state is not None:
                # ! set column_name
                if isinstance(column_name, str):
                    column_name = [column_name, 'State']
                elif isinstance(column_name, list):
                    if 'State' not in column_name:
                        column_name.append('State')

                # ! set query
                if isinstance(component_name, str):
                    lookup = [component_name, component_state]
            else:
                lookup = component_name

            # NOTE: search
            try:
                payload = TableReferenceC.make_payload(
                    databook_id=databook_id,
                    table_id=table_id,
                    column_name=column_name,
                    lookup=lookup,
                    query=query,
                    matrix_tb=matrix_tb
                )
            except Exception as e:
                logging.error(f"Table search error {e}")
                payload = None

            # NOTE: check availability
            if payload:
                # check
                if len(payload) > 0:
                    if dataframe:
                        df = pd.DataFrame(
                            payload,
                            columns=[
                                'header', 'symbol', 'records', 'unit'
                            ]
                        )
                        return df
                    else:
                        return payload
                else:
                    raise Exception(
                        "Data for {} not available!".format(component_name))
            else:
                raise Exception(
                    "Data for {} not available!".format(component_name))
        else:
            print("databook and table id required!")
    except Exception as e:
        raise Exception(f'Reading data error {e}')

is_component_available(component, databook, table, column_names=['Name', 'Formula'], component_key='Name-State', res_format='dict')

Check if a component is available in the specified databook and table. A component is defined as: - name-state: carbon dioxide-g - formula-state: CO2-g

Parameters

component : Component The component to check. databook : int | str The databook id or name. table : int | str The table id or name. column_names : List[str], optional List of column names to search in, by default ['Name', 'Formula']. component_key : Literal['Name-State', 'Formula-State'], optional The key to use for identifying the component, by default 'Name-State'. res_format : Literal['dict', 'json', 'str'], optional The format of the returned result, by default 'json'.

Returns

str | dict[str, str] Summary of the component availability.

Notes

• Table should contain columns for 'Name', 'Formula', and 'State'. Otherwise an error will be raised.

Source code in pyThermoDB/docs/thermo.py

def is_component_available(
    self,
    component: Component,
    databook: int | str,
    table: int | str,
    column_names: List[str] = ['Name', 'Formula'],
    component_key: Literal['Name-State', 'Formula-State'] = 'Name-State',
    res_format: Literal['dict', 'json', 'str'] = 'dict'
) -> Union[str, dict[str, str]]:
    '''
    Check if a component is available in the specified databook and table. A component is defined as:
    - name-state: carbon dioxide-g
    - formula-state: CO2-g

    Parameters
    ----------
    component : Component
        The component to check.
    databook : int | str
        The databook id or name.
    table : int | str
        The table id or name.
    column_names : List[str], optional
        List of column names to search in, by default ['Name', 'Formula'].
    component_key : Literal['Name-State', 'Formula-State'], optional
        The key to use for identifying the component, by default 'Name-State'.
    res_format : Literal['dict', 'json', 'str'], optional
        The format of the returned result, by default 'json'.

    Returns
    -------
    str | dict[str, str]
        Summary of the component availability.

    Notes
    -----
    - Table should contain columns for 'Name', 'Formula', and 'State'. Otherwise an error will be raised.
    '''
    try:
        # SECTION: Validate input
        if not isinstance(component, Component):
            raise ValueError(
                "Invalid component. Must be an instance of Component class.")
        if (
            not component.name and
            not component.formula and
            not component.state
        ):
            raise ValueError(
                "Component must have at least a name or a formula.")
        if not column_names or not isinstance(column_names, list):
            raise ValueError(
                "column_names must be a non-empty list of strings.")
        if len(column_names) != 2:
            raise ValueError(
                "column_names must contain exactly two elements: ['Name', 'Formula'].")

        # SECTION: Check component_key validity
        if component_key not in ['Name-State', 'Formula-State']:
            raise ValueError(
                "Invalid component_key. Must be 'Name-State' or 'Formula-State'.")

        # NOTE: create component id band query
        component_id = None
        query = None

        # check
        if component_key == 'Name-State':
            # set
            component_id = f"{component.name}-{component.state}"
            # query
            query = f'Name.str.lower() == "{component.name.lower()}" and State.str.lower() == "{component.state.lower()}"'
        elif component_key == 'Formula-State':
            # set
            component_id = f"{component.formula}-{component.state}"
            # query
            query = f'Formula.str.lower() == "{component.formula.lower()}" and State.str.lower() == "{component.state.lower()}"'

        if component_id is None:
            raise ValueError("Component ID could not be determined.")

        if query is None:
            raise ValueError("Query could not be determined.")

        # SECTION: find ids
        # find databook zero-based id (real)
        db, db_name, db_rid = self.find_databook(databook)
        # databook id (non-zero-based id)
        databook_id = db_rid + 1

        # find table zero-based id
        tb_id, tb_name = self.find_table(databook, table)
        # table id (non-zero-based id)
        table_id = tb_id + 1

        # SECTION: Check if the component exists in the specified databook and table
        availability = self.check_component_local(
            component_name=component_id,
            databook_id=databook_id,
            table_id=table_id,
            column_name=query,
            query=True,
        )

        # res
        res_dict = {
            'databook_id': databook_id,
            'databook_name': db_name,
            'table_id': table_id,
            'table_name': tb_name,
            'component_name': component_id,
            'availability': availability
        }

        # json
        res_json = json.dumps(res_dict, indent=4)

        # check
        if res_format == 'json':
            return res_json
        elif res_format == 'dict':
            return res_dict
        elif res_format == 'str':
            return res_json
        else:
            raise ValueError('Invalid res_format')
    except Exception as e:
        raise Exception(f"Error checking component availability: {e}")

list_components(res_format='dict')

List all components in the databook

Parameters

res_format : Literal['list', 'dict', 'json'] result format, 'list', 'dict' or 'json'

Returns

ListComponents list of components in the databook

Source code in pyThermoDB/docs/thermo.py

def list_components(
    self,
    res_format: Literal[
        'list', 'dict', 'json'
    ] = 'dict'
) -> ListComponents:
    """
    List all components in the databook

    Parameters
    ----------
    res_format : Literal['list', 'dict', 'json']
        result format, 'list', 'dict' or 'json'

    Returns
    -------
    ListComponents
        list of components in the databook
    """
    try:
        # exec
        res, _ = self.__list_components()

        # res dict
        res_dict = {
            'components': res
        }

        # json
        res_json = json.dumps(res_dict, indent=4)

        # check res_format
        if res_format == 'list':
            return res
        elif res_format == 'dict':
            return res_dict
        elif res_format == 'json':
            return res_json
        else:
            raise ValueError("Invalid res_format")

    except Exception as e:
        raise Exception(f'Listing component error {e}')

list_components_info(res_format='dict')

List components information in the databook

Parameters

res_format : Literal['list', 'dict', 'json'] result format, 'list', 'dict' or 'json'

Returns

ListComponentsInfo list of components information in the databook

Source code in pyThermoDB/docs/thermo.py

def list_components_info(
        self,
        res_format: Literal[
            'list', 'dict', 'json'
        ] = 'dict'
) -> ListComponentsInfo:
    """
    List components information in the databook

    Parameters
    ----------
    res_format : Literal['list', 'dict', 'json']
        result format, 'list', 'dict' or 'json'

    Returns
    -------
    ListComponentsInfo
        list of components information in the databook
    """
    try:
        # from async
        _, res = self.__list_components()

        # dict
        res_dict = {f'record-{i+1}': item for i, item in enumerate(res)}
        # json
        res_json = json.dumps(res_dict, indent=4)

        # check res_format
        if res_format == 'list':
            return res
        elif res_format == 'dict':
            return res_dict
        elif res_format == 'json':
            return res_json
        else:
            raise ValueError("Invalid res_format")

    except Exception as e:
        raise Exception(f'Listing component info error {e}')

list_databooks(res_format='dataframe')

List all databooks

Parameters

res_format : Literal['list', 'dataframe', 'json'] Format of the returned data. Defaults to 'dataframe'.

Returns

res : list | pandas.DataFrame | str Databook list in the specified format. - 'list': List of dictionaries containing databook information. - 'dataframe': Pandas DataFrame containing databook information. - 'json': JSON string representing the databook list.

Source code in pyThermoDB/docs/thermo.py

def list_databooks(
        self,
        res_format: Literal[
            'list', 'dataframe', 'json'
        ] = 'dataframe'):
    '''
    List all databooks

    Parameters
    -----------
    res_format : Literal['list', 'dataframe', 'json']
        Format of the returned data. Defaults to 'dataframe'.

    Returns
    -------
    res : list | pandas.DataFrame | str
        Databook list in the specified format.
        - 'list': List of dictionaries containing databook information.
        - 'dataframe': Pandas DataFrame containing databook information.
        - 'json': JSON string representing the databook list.
    '''
    try:
        # databook list
        res = self.get_databooks()
        # check
        if res_format == 'list':
            return res[0]
        elif res_format == 'dataframe':
            return res[1]
        elif res_format == 'json':
            return res[2]
        else:
            raise ValueError('Invalid res_format')
    except Exception as e:
        raise Exception(f"databooks loading error! {e}")

list_descriptions(res_format='dataframe')

List all descriptions of databooks and tables

Parameters

res_format : Literal['dict', 'list', 'dataframe', 'json'] Format of the returned data. Defaults to 'dataframe'.

Returns

res : ListDatabookDescriptions List of descriptions in the specified format.

Source code in pyThermoDB/docs/thermo.py

def list_descriptions(
        self,
        res_format: Literal[
            'dict', 'list', 'dataframe', 'json'
        ] = 'dataframe'
) -> ListDatabookDescriptions:
    '''
    List all descriptions of databooks and tables

    Parameters
    ----------
    res_format : Literal['dict', 'list', 'dataframe', 'json']
        Format of the returned data. Defaults to 'dataframe'.

    Returns
    -------
    res : ListDatabookDescriptions
        List of descriptions in the specified format.
    '''
    try:
        # load descriptions
        res = self.get_descriptions()

        # check
        if res_format == 'dict':
            return res[0]
        elif res_format == 'list':
            return res[1]
        elif res_format == 'json':
            return res[2]
        elif res_format == 'dataframe':
            return res[3]
        else:
            raise ValueError('Invalid python res_format')

    except Exception as e:
        raise Exception(f"Descriptions loading error! {e}")

list_symbols(res_format='dataframe')

List all symbols

Parameters

res_format : Literal['dict', 'list', 'dataframe', 'json'] Format of the returned data. Defaults to 'dataframe'.

Source code in pyThermoDB/docs/thermo.py

def list_symbols(
        self,
        res_format: Literal[
            'dict', 'list', 'dataframe', 'json'
        ] = 'dataframe'):
    '''
    List all symbols

    Parameters
    ----------
    res_format : Literal['dict', 'list', 'dataframe', 'json']
        Format of the returned data. Defaults to 'dataframe'.
    '''
    try:
        # load symbols
        res = self.get_symbols()

        # check format
        if res_format == 'dict':
            return res[0]
        elif res_format == 'list':
            return res[1]
        elif res_format == 'json':
            return res[2]
        elif res_format == 'dataframe':
            return res[3]
        else:
            raise ValueError('Invalid res_format')

    except Exception as e:
        raise Exception(f"Symbols loading error! {e}")

list_tables(databook, res_format='dataframe')

List all tables in the selected databook

Parameters

databook : int | str databook id or name res_format : Literal['list', 'dataframe', 'json'] Format of the returned data. Defaults to 'dataframe'.

Returns

table list : list | pandas.DataFrame | str | dict[str, str] list of tables

Source code in pyThermoDB/docs/thermo.py

def list_tables(self,
                databook: int | str,
                res_format: Literal[
                    'list', 'dataframe', 'json', 'dict'
                ] = 'dataframe'
                ) -> list[list[str]] | pd.DataFrame | str | dict[str, str]:
    '''
    List all tables in the selected databook

    Parameters
    ----------
    databook : int | str
        databook id or name
    res_format : Literal['list', 'dataframe', 'json']
        Format of the returned data. Defaults to 'dataframe'.

    Returns
    -------
    table list : list | pandas.DataFrame | str | dict[str, str]
        list of tables
    '''
    try:
        # manual databook setting
        db, db_name, db_id = self.find_databook(databook)
        # table list
        res = self.get_tables(db_name)
        # check
        if res_format == 'list':
            return res[0]
        elif res_format == 'dataframe':
            return res[1]
        elif res_format == 'json':
            return res[2]
        elif res_format == 'dict':
            return res[3]
        else:
            raise ValueError('Invalid res_format')
    except Exception as e:
        raise Exception("Table loading error!,", e)

matrix_data_load(databook, table)

Gives table contents as:

* Table type
* Data and equations numbers

Parameters

databook : int | str databook id or name table : str table name

Returns

object : TableMatrixData table object with data loaded

Source code in pyThermoDB/docs/thermo.py

def matrix_data_load(
    self,
    databook: int | str,
    table: int | str
) -> TableMatrixData:
    '''
    Gives table contents as:

        * Table type
        * Data and equations numbers

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : str
        table name

    Returns
    -------
    object : TableMatrixData
        table object with data loaded
    '''
    try:
        # table type
        # tb_type = ''
        # table name
        table_name = ''
        # table data
        table_data = []
        # databook id | name
        db, db_name, db_id = self.find_databook(databook)
        # get the tb
        tb = self.select_table(databook, table)

        # check
        if tb:
            # table name
            table_name = tb['table']

            # matrix-data/matrix-equation
            if tb['matrix_data'] is not None:
                # tb_type = TableTypes.MATRIX_DATA.value

                # table data
                table_data = tb['matrix_data']

                # data no
                return TableMatrixData(db_name, table_name, table_data)
            else:
                raise Exception('Table loading error!')
        else:
            raise Exception('Table not found!')
    except Exception as e:
        raise Exception(f"Table loading error {e}")

matrix_equation_load(databook, table)

Display table header columns and other info

Parameters

databook : int | str databook id or name table : str table name

Returns

object: TableMatrixEquation

Notes

1. table should be a string

Source code in pyThermoDB/docs/thermo.py

def matrix_equation_load(
    self,
    databook: int | str,
    table: int | str
) -> TableMatrixEquation:
    '''
    Display table header columns and other info

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : str
        table name

    Returns
    -------
    object: TableMatrixEquation

    Notes
    -----
    1. table should be a string
    '''
    try:
        # table type
        # tb_type = ''
        # table name
        table_name = ''
        # table equations
        table_equations = []
        # databook id | name
        db, db_name, db_id = self.find_databook(databook)
        # get the tb
        tb = self.select_table(databook, table)

        # check
        if tb:
            # table name
            table_name = tb['table']

            # matrix-data/matrix-equation
            if tb['matrix_equations'] is not None:
                # tb_type = TableTypes.MATRIX_EQUATIONS.value

                for item in tb['matrix_equations']:
                    table_equations.append(item)

                # create table equation
                return TableMatrixEquation(
                    db_name,
                    table_name,
                    table_equations
                )
            else:
                raise Exception('Table loading error!')
        else:
            raise Exception('Table loading error!')

    except Exception as e:
        raise Exception(f"Table loading error {e}")

search_databook(search_terms, column_names=['Name', 'Formula'], res_format='dict', search_mode='exact')

Search a term through all databook for instance a component name

Parameters

search_terms : list[str] search terms as list, e.g. ['Carbon dioxide','CO2'] column_names : list[str] column names to search, e.g. ['Name', 'Formula'] res_format : Literal['list', 'dataframe', 'json', 'dict'] result format, 'list', 'dataframe', 'json' or 'dict' search_mode : Literal['exact', 'similar'] search mode, 'exact' or 'similar'

Returns

ComponentSearchResult search results

Source code in pyThermoDB/docs/thermo.py

def search_databook(
        self,
        search_terms: list[str],
        column_names: list[str] = ['Name', 'Formula'],
        res_format: Literal[
            'list', 'dataframe', 'json', 'dict'
        ] = 'dict',
        search_mode: Literal[
            'exact', 'similar'
        ] = 'exact'
) -> ComponentSearch:
    """
    Search a term through all databook for instance a component name

    Parameters
    ----------
    search_terms : list[str]
        search terms as list, e.g. ['Carbon dioxide','CO2']
    column_names : list[str]
        column names to search, e.g. ['Name', 'Formula']
    res_format : Literal['list', 'dataframe', 'json', 'dict']
        result format, 'list', 'dataframe', 'json' or 'dict'
    search_mode : Literal['exact', 'similar']
        search mode, 'exact' or 'similar'

    Returns
    -------
    ComponentSearchResult
        search results
    """
    try:
        # call async function
        res = self.__search_databook(
            search_terms,
            search_mode,
            column_names
        )

        # check
        if len(res) == 0:
            logging.warning(
                f'No results found for the search terms: {search_terms}, search mode: {search_mode}'
            )
            return []

        # dict
        res_dict = {f'record-{i+1}': item for i, item in enumerate(res)}

        res_dict = dict(
            {
                'message': f'results found for the search terms : {search_terms}, search mode : {search_mode}'
            }, **res_dict
        )

        # NOTE: result settings
        # check res_format
        if res_format == 'list':
            return res
        elif res_format == 'dataframe':
            # dataframe
            return pd.DataFrame(res)
        elif res_format == 'json':
            # json
            return json.dumps(res_dict, indent=4)
        elif res_format == 'dict':
            return res_dict
        else:
            raise ValueError("Invalid res_format")
    except Exception as e:
        raise Exception(f'Search databook error {e}')

select_table(databook, table)

Select a table structure

Parameters

databook : int | str databook id or name table : int | str table id or name (non-zero-based id) dataframe: book if True, return a dataframe

Returns

tb : DataBookTableTypes table object

Source code in pyThermoDB/docs/thermo.py

def select_table(
    self,
    databook: int | str,
    table: int | str
) -> DataBookTableTypes:
    '''
    Select a table structure

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : int | str
        table id or name (non-zero-based id)
    dataframe: book
        if True, return a dataframe

    Returns
    -------
    tb : DataBookTableTypes
        table object
    '''
    try:
        # set
        tb_id = -1
        tb_name = ''

        # find databook
        db, db_name, db_id = self.find_databook(databook)

        # find table
        if isinstance(table, int):
            # tb
            tb = self.get_table(db_name, table-1)
        elif isinstance(table, str):
            # get tables
            tables = self.list_tables(databook=db_name, res_format='list')
            # check
            if isinstance(tables, list):
                # looping
                for i, item in enumerate(tables):
                    # check
                    if isinstance(item, list):
                        # table name
                        tb_name = item[0]
                        if tb_name == table.strip():
                            # zero-based id
                            tb_id = i
                            break
                    else:
                        raise ValueError(f"list {item} not found.")
                # tb
                # FIXME
                tb = self.get_table(db, tb_id)
            else:
                raise ValueError(f"table {table} not found.")
        else:
            raise ValueError("table must be int or str.")

        # res
        return tb
    except Exception as e:
        # Log or print the error for debugging purposes
        raise Exception(
            f"An error occurred while selecting the table: {e}")

table_data(databook, table, res_format='dataframe')

Get all table elements (display a table)

Parameters

databook : str | int databook name or id table : str | int table name or id res_format : Literal['dataframe', 'dict','json'] Format of the returned data. Defaults to 'dataframe'.

Returns

tb_data : Pandas.DataFrame | list | str table data in the specified format.

Source code in pyThermoDB/docs/thermo.py

def table_data(
    self,
    databook: str | int,
    table: str | int,
    res_format: Literal[
        'dataframe', 'list', 'json'
    ] = 'dataframe'
) -> pd.DataFrame | List[
    Dict[Hashable, Optional[float | int | str]]
] | str | Dict[str, pd.DataFrame]:
    '''
    Get all table elements (display a table)

    Parameters
    ----------
    databook : str | int
        databook name or id
    table : str | int
        table name or id
    res_format : Literal['dataframe', 'dict','json']
        Format of the returned data. Defaults to 'dataframe'.

    Returns
    -------
    tb_data : Pandas.DataFrame | list | str
        table data in the specified format.
    '''
    try:
        # find databook zero-based id (real)
        db, db_name, db_rid = self.find_databook(databook)
        # databook id
        databook_id = db_rid + 1

        # find table zero-based id
        tb_id, tb_name = self.find_table(databook, table)
        # table id
        table_id = tb_id + 1

        # SECTION: set api
        TableReferenceC = TableReference(custom_ref=self.custom_ref)
        # REVIEW: load table
        tb_data = TableReferenceC.load_table(databook_id, table_id)

        # NOTE: check tb_data
        if isinstance(tb_data, pd.DataFrame):
            # ! dataframe
            # convert to list of dicts
            tb_list_dict = tb_data.to_dict(orient='records')
            # to json
            tb_json = tb_data.to_json(orient='records')

            # NOTE: check res_format
            if res_format == 'dataframe':
                return tb_data
            elif res_format == 'list':
                return tb_list_dict
            elif res_format == 'json':
                return tb_json
            else:
                raise ValueError('Invalid res_format')
        else:
            raise ValueError('Invalid table data format')
    except Exception as e:
        raise Exception(f"Loading matrix data failed {e}")

table_description(databook, table, res_format='str')

Get information about a databook.

Parameters

databook : int | str databook id or name table : int | str table id or name res_format : Literal['str', 'json', 'dict'] Format of the returned data. Defaults to 'str'.

Returns

str | dict Description of the table in the specified format. - 'str': Returns the description as a string. - 'dict': Returns a dictionary with the description. - 'json': Returns a JSON string with the description.

Source code in pyThermoDB/docs/thermo.py

def table_description(
    self,
    databook: int | str,
    table: int | str,
    res_format: Literal[
        'str', 'json', 'dict'
    ] = 'str'
) -> str | dict:
    '''
    Get information about a databook.

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    res_format : Literal['str', 'json', 'dict']
        Format of the returned data. Defaults to 'str'.

    Returns
    -------
    str | dict
        Description of the table in the specified format.
        - 'str': Returns the description as a string.
        - 'dict': Returns a dictionary with the description.
        - 'json': Returns a JSON string with the description.
    '''
    try:
        # get the tb
        tb = self.select_table(databook, table)

        # check
        if tb:
            # descriptions
            descriptions = tb['description']

            # to dict
            des_dict = {
                "table-description": descriptions
            }

            # check
            if descriptions:
                # check
                if res_format == 'str':
                    return descriptions
                elif res_format == 'dict':
                    return des_dict
                elif res_format == 'json':
                    return json.dumps(des_dict)
                else:
                    raise ValueError('Invalid res_format')
            else:
                return "No description found!"
        else:
            raise ValueError("No such table found!")

    except Exception as e:
        # Log or print the error for debugging purposes
        raise Exception(
            f"An error occurred while getting the databook info: {e}")

table_info(databook, table, res_format='dataframe')

Gives table contents as:

* Table type
* Data and equations numbers

Parameters

databook : int | str databook id or name table : int | str table id or name dataframe: book if True, return a dataframe

Returns

tb_summary : dict | pandas.DataFrame | str table summary

Notes

1. The default value of dataframe is True, the return value (tb_summary) is Pandas Dataframe

Source code in pyThermoDB/docs/thermo.py

def table_info(
    self,
    databook: int | str,
    table: int | str,
    res_format: Literal[
        'dict', 'dataframe', 'json'
    ] = 'dataframe'
) -> dict[str, int | str] | pd.DataFrame | str:
    '''
    Gives table contents as:

        * Table type
        * Data and equations numbers

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : int | str
        table id or name
    dataframe: book
        if True, return a dataframe

    Returns
    -------
    tb_summary : dict | pandas.DataFrame | str
        table summary

    Notes
    -----
    1. The default value of dataframe is True, the return value (tb_summary) is Pandas Dataframe
    '''
    try:
        # table type
        tb_type = ''
        # table name
        table_name = ''
        # table equations
        table_equations = []
        # table data
        table_data = []
        # equation no
        equation_no = 0
        matrix_equation_no = 0
        # data no
        data_no = 0
        matrix_data_no = 0
        # get the tb
        tb = self.select_table(databook, table)

        # check
        if tb:
            # table name
            table_name: str = tb['table']
            # check
            if table_name is None:
                raise Exception(f"table name {table_name} not found!")

            # check data/equations and matrix-data/matrix-equation
            # tb_type = 'Equation' if tb['equations'] is not None else 'Data'

            if tb['data'] is not None:
                tb_type = 'Data'
            if tb['equations'] is not None:
                tb_type = 'Equation'
            if tb['matrix_equations'] is not None:
                tb_type = 'Matrix-Equation'
            if tb['matrix_data'] is not None:
                tb_type = 'Matrix-Data'

            # ! check equations
            if tb_type == 'Equation' and tb['equations'] is not None:
                for item in tb['equations']:
                    table_equations.append(item)

                # equation no
                equation_no = len(table_equations)

            # ! check data
            if tb_type == 'Data' and tb['data'] is not None:
                table_data = [*tb['data']]

                # data no
                data_no = 1

            # ! check matrix-equation
            if tb_type == 'Matrix-Equation' and tb['matrix_equations'] is not None:
                for item in tb['matrix_equations']:
                    table_equations.append(item)

                # equation no
                matrix_equation_no = len(table_equations)

            # ! check matrix-data
            if tb_type == 'Matrix-Data' and tb['matrix_data'] is not None:
                # set
                table_data = [*tb['matrix_data']]

                # data no
                matrix_data_no = 1

            # data
            tb_summary: Dict[str, str | int] = {
                "Table Name": table_name,
                "Type": tb_type,
                "Equations": equation_no,
                "Data": data_no,
                "Matrix-Equations": matrix_equation_no,
                "Matrix-Data": matrix_data_no
            }

            # json
            tb_summary_json = json.dumps(tb_summary)

        else:
            raise ValueError("No such table")

        if res_format == 'dataframe':
            # column names
            column_names = ['Table Name', 'Type', 'Equations',
                            'Data', 'Matrix-Equations', 'Matrix-Data']
            # dataframe
            df = pd.DataFrame([tb_summary], columns=column_names)
            return df
        elif res_format == 'json':
            return tb_summary_json
        elif res_format == 'dict':
            return tb_summary
        else:
            raise ValueError("Invalid res_format")
    except Exception as e:
        raise Exception(f"Table loading error {e}")

table_view(databook, table)

Display a table header columns and other info

Parameters

databook : str | int databook name or id table : str | int table name or id

Returns

str HTML content of the table view page.

Source code in pyThermoDB/docs/thermo.py

def table_view(self, databook: str | int, table: str | int):
    '''
    Display a table header columns and other info

    Parameters
    ----------
    databook : str | int
        databook name or id
    table : str | int
        table name or id

    Returns
    -------
    str
        HTML content of the table view page.
    '''
    try:
        # SECTION: check if jinja2 is installed
        try:
            from jinja2 import Environment, FileSystemLoader
        except ImportError:
            raise ImportError(
                "Jinja2 is not installed. Please install it using 'pip install jinja2'.")

        # SECTION: detect table type
        tb_info_res_ = self.table_info(databook, table, res_format='dict')

        # NOTE: databook name
        db, db_name, db_rid = self.find_databook(databook)

        # NOTE: table name
        tb_id, tb_name = self.find_table(databook, table)

        # res
        tb_res = None

        # if
        if isinstance(tb_info_res_, dict):
            # check
            if tb_info_res_['Type'] == 'Equation':  # ! equation
                # load table equation
                tb_res = self.table_data(databook, table)
            elif tb_info_res_['Type'] == 'Data':  # ! data
                # load table data
                tb_res = self.table_data(databook, table)
            elif tb_info_res_['Type'] == 'Matrix-Equation':  # ! matrix-equation
                # load table equation
                tb_res = self.table_data(databook, table)
            elif tb_info_res_['Type'] == 'Matrix-Data':  # ! matrix-data
                # load table equation
                tb_res = self.table_data(databook, table)
            else:
                raise Exception('No data/equation found!')

            # SECTION: convert dataframe to dict
            # check
            if isinstance(tb_res, pd.DataFrame):
                # NOTE: convert to list of dict
                tb_res = tb_res.to_dict(orient='records')

            # SECTION: web application
            # check jinja2 installed
            # from jinja2 import Environment, FileSystemLoader
            # res
            # return tb_res
            # NOTE: tojson function
            def tojson(obj):
                return json.dumps(obj)

            # NOTE: url_for function
            def url_for(endpoint, filename=None):
                """
                Generate absolute paths for static files when opening the HTML file directly.
                """
                if endpoint == 'static':
                    # Get the directory of the current script
                    # current path
                    current_path = os.path.dirname(__file__)

                    # Go back to the parent directory (pyThermoDB)
                    parent_path = os.path.abspath(
                        os.path.join(current_path, '..'))

                    # static path
                    static_path = os.path.join(parent_path, 'static')

                    # base_dir = os.path.dirname(os.path.abspath(__file__))
                    # parent_dir = os.path.dirname(os.path.dirname(__file__))
                    # static directory
                    static_dir = f'file://{os.path.join(static_path, filename).replace(os.sep, "/")}'
                    return static_dir
                return '#'

            def render_page(databook_name: str,
                            table_name: str,
                            sample_data: List[Dict],
                            page: int = 1,
                            rows_per_page: int = 50,
                            theme: Literal['light', 'dark'] = "light"):
                """
                Render the HTML page using Jinja2 templates

                Parameters
                ----------
                databook_name : str
                    Name of the databook
                table_name : str
                    Name of the table
                sample_data : list
                    List of dictionaries containing table data
                page : int, optional
                    Current page number (default is 1)
                rows_per_page : int, optional
                    Number of rows per page (default is 50)
                theme : str, optional
                    Theme for the table ('light' or 'dark', default is 'light')
                """
                # Define text colors for each theme to ensure visibility
                text_colors = {
                    'light': {
                        'primary': '#212529',  # Dark text for light backgrounds
                        'secondary': '#495057',
                        'muted': '#6c757d'
                    },
                    'dark': {
                        'primary': '#f8f9fa',  # Light text for dark backgrounds
                        'secondary': '#e9ecef',
                        'muted': '#adb5bd'
                    }
                }

                # extract data
                sample_data = sample_data[2:]
                # Calculate pagination values
                total_items = len(sample_data)
                total_pages = (
                    total_items + rows_per_page - 1) // rows_per_page

                # SECTION: Setup Jinja2 environment
                # current path
                current_path = os.path.dirname(__file__)

                # Go back to the parent directory (pyThermoDB)
                parent_path = os.path.abspath(
                    os.path.join(current_path, '..'))

                # template path
                template_path = os.path.join(parent_path, 'templates')

                template_loader = FileSystemLoader(
                    searchpath=template_path)
                template_env = Environment(loader=template_loader)

                # Add the function to Jinja2 environment globals
                template = template_env.get_template('table_view.html')

                # SECTION: Get the template and render it with the data
                rendered_html = template.render(
                    title='PyThermoDB Table Viewer',
                    app_name='PyThermoDB Viewer',
                    databook_name=databook_name,
                    table_name=table_name,
                    table_title='Chemical Compounds Data',
                    table_data=sample_data,
                    total_data=total_items,
                    tojson=tojson,
                    url_for=url_for,
                    current_page=page,
                    rows_per_page=rows_per_page,
                    total_pages=total_pages,
                    default_theme=theme,
                    text_colors=text_colors,
                    footer_text=(
                        'PyThermoDB Table Viewer - A web application to display and '
                        'interact with thermodynamic data tables.'
                    ),
                    company='PyThermoDB Project',
                    app_version=__version__,
                )

                return rendered_html

            # generate HTML content for the requested page
            html_content = render_page(
                db_name,
                tb_name,
                tb_res,
                page=1,
                rows_per_page=50,
                theme='light'
            )

            # temporary file to store the HTML content
            with tempfile.NamedTemporaryFile(
                'w', delete=False, suffix='.html'
            ) as temp_file:
                temp_file.write(html_content)
                # NOTE: the file is not deleted after closing, so we can open it in the
                # browser
                webbrowser.open(temp_file.name)

            # Return the path to the temporary file in case needed elsewhere
            return temp_file.name

        else:
            raise Exception('Table loading error!')
    except Exception as e:
        raise Exception(f"Table loading error {e}")

tables_view()

Display all tables in the browser.

Source code in pyThermoDB/docs/thermo.py

def tables_view(self):
    """
    Display all tables in the browser.
    """
    try:
        # SECTION: check if jinja2 is installed
        try:
            from jinja2 import Environment, FileSystemLoader
        except ImportError:
            raise ImportError(
                "Jinja2 is not installed. Please install it using 'pip install jinja2'.")

        # SECTION: load data
        data_ = self.list_descriptions(res_format='dict')

        # check
        if not isinstance(data_, dict):
            raise ValueError("data_ is not a dictionary!")

        # card data
        card_data = []

        # looping through databooks
        for k, v in data_.items():
            db_name = k
            db_id = v['DATABOOK-ID']

            # looping through tables
            for k_, v_ in v.items():
                if k_ == 'DATABOOK-ID':
                    continue

                _table_id = v_['TABLE-ID']
                _table_description = v_['DESCRIPTION']
                _table_name = k_

                # data load
                _table_data = self.table_data(
                    db_id, _table_id, res_format='list')

                # collect data
                card_data.append({
                    'db_name': db_name,
                    'db_id': db_id,
                    'table_name': _table_name,
                    'table_id': _table_id,
                    'table_description': _table_description,
                    'table_data': _table_data,
                    'table_data_length': len(_table_data),
                })

        # SECTION: render HTML page
        # init launcher
        app = Launcher()
        # pass data
        return app.launch(card_data)

    except Exception as e:
        raise Exception(f"Error displaying tables: {e}")

tableref

TableReference

Bases: ManageData

Class to load csv/yml/json files

Source code in pyThermoDB/docs/tableref.py

class TableReference(ManageData):
    """
    Class to load csv/yml/json files
    """

    def __init__(self, custom_ref: Optional[CustomRef] = None):
        # custom ref
        self.custom_ref = custom_ref

        # current path
        current_path = os.path.dirname(__file__)

        # Go back to the parent directory (pyThermoDB)
        parent_path = os.path.abspath(os.path.join(current_path, '..'))

        # Now navigate to the data folder
        data_path = os.path.join(parent_path, 'data')

        # Set the path to the "data" folder
        self.path = data_path
        # super
        ManageData.__init__(self, custom_ref=custom_ref)

    def load_external_csv(self, custom_ref: CustomRef) -> list[str]:
        '''
        Load external csv file paths

        Parameters
        ----------
        custom_ref : CustomRef
            custom ref
        '''
        path_external = custom_ref.csv_paths
        return path_external

    def list_databooks(self):
        '''
        list databooks
        '''
        _, df, _ = self.get_databooks()
        return df

    def list_tables(
        self,
        databook: int | str,
        res_format: Literal[
            'list', 'dataframe', 'json', 'dict'
        ] = 'dataframe'
    ) -> list[list[str]] | pd.DataFrame | str | dict[str, str]:
        '''
        List all tables in the selected databook

        Parameters
        ----------
        databook : int | str
            databook id or name
        res_format : Literal['list', 'dataframe', 'json']
            Format of the returned data. Defaults to 'dataframe'.

        Returns
        -------
        table list : list | pandas.DataFrame | str | dict[str, str]
            list of tables
        '''
        try:
            # manual databook setting
            db, db_name, db_id = self.find_databook(databook)
            # table list
            res = self.get_tables(db_name)
            # check
            if res_format == 'list':
                return res[0]
            elif res_format == 'dataframe':
                return res[1]
            elif res_format == 'json':
                return res[2]
            elif res_format == 'dict':
                return res[3]
            else:
                raise ValueError('Invalid res_format')
        except Exception as e:
            raise Exception("Table loading error!,", e)

    def load_table(
        self,
        databook_id: int,
        table_id: int
    ) -> pd.DataFrame:
        """
        Load a `csv file` from app directory or external reference
        and convert it to a pandas dataframe.
        If the table is a matrix data, it will return a dictionary of dataframes.
        If the table is a data or equations, it will return a single dataframe.

        Parameters
        ----------
        databook_id : int
            databook id (non-zero-based id)
        table_id : int
            table id (non-zero-based id)

        Returns
        -------
        pandas DataFrame
            pandas DataFrame
        """
        try:
            # init vars
            file_data = None
            file_item_data = None
            file_path = None

            # NOTE:
            # table
            tb = self.get_table(databook_id-1, table_id-1)
            # table type
            tb_type = tb['table_type']

            # table name
            table_name = tb['table']
            # table file
            file_name = table_name + '.csv'

            # check table exists in local or external references
            reference_local_no = self.reference_local_no

            # SECTION: table file path
            # local
            if databook_id <= reference_local_no:
                # set file path
                file_path = os.path.join(self.path, file_name)
            else:
                # check
                if self.custom_ref is None:
                    raise ValueError('No custom reference provided')

                # NOTE: load external path
                path_external = self.load_external_csv(self.custom_ref)

                # SECTION: check if the file exists in the external paths
                file_path = None
                # check
                if len(path_external) > 0:
                    # check csv paths
                    # csv file names
                    file_names = [
                        os.path.basename(path) for path in path_external
                    ]
                    # check csv file
                    for item in file_names:
                        if item == file_name:
                            file_path = path_external[file_names.index(item)]
                            break

                # SECTION: load values from custom reference (if exists in the yml/md file)
                # ! check both yml and md files
                if tb_type and file_path is None:
                    # load table data
                    table_data = self.retrieve_data(
                        tb, tb_type)

                    # NOTE: load structure
                    table_structure = tb.get('table_structure', None)

                    # check
                    if table_structure is None:
                        raise Exception(
                            f"Table data is None for {file_name}.")

                    # NOTE: table structure
                    columns = table_structure.get('COLUMNS', None)
                    symbol = table_structure.get('SYMBOL', None)
                    unit = table_structure.get('UNIT', None)

                    # check
                    if columns is None or symbol is None or unit is None:
                        raise Exception(
                            f"Table data is None for {file_name}.")

                    # SECTION: used by matrix data
                    # NOTE: table_values
                    values = tb.get('table_values', None)
                    # NOTE: table_items
                    items = tb.get('table_items', None)

                    # NOTE: load values
                    if tb_type == TableTypes.DATA.value:
                        # ! data & matrix data

                        # check
                        if values is None:
                            raise Exception(
                                f"Table data is None for {file_name}.")

                        # NOTE: add to file data
                        file_data = []
                        # ! add to dataframe header
                        # file_data.append(columns)
                        file_data.append(symbol)
                        file_data.append(unit)
                        file_data.extend(values)

                    elif tb_type == TableTypes.MATRIX_DATA.value:
                        # ! matrix data

                        # NOTE: values or items
                        # check
                        if values is None:
                            # check items
                            if items is None:
                                # ! raise exception as no values or items
                                raise Exception(
                                    f"Table data is None for {file_name}.")

                        # NOTE: matrix data
                        matrix_data = tb.get('matrix_data', None)
                        # check
                        if matrix_data is None:
                            raise Exception(
                                f"Table data is None for {file_name}.")

                        # matrix symbol
                        matrix_symbol = matrix_data.get('MATRIX-SYMBOL', None)

                        # check
                        if matrix_symbol is None:
                            raise Exception(
                                f"Table data is None for {file_name}.")

                        # size of matrix symbols
                        matrix_symbol_len = len(matrix_symbol)

                        # SECTION: values
                        if values and isinstance(values, list):
                            # # size of matrix symbols
                            # component_idx_len = len(values) - 2

                            # # ! No., Name, Formula are necessary for matrix data
                            # header_ = ['None', 'None', 'None']
                            # component_idx = [str(i) for i in range(
                            #     1, component_idx_len+1)]*matrix_symbol_len

                            # # updated header
                            # header_ = header_ + component_idx

                            # # updated values
                            # values_ = [header_, *values]
                            # NOTE: check columns contains Mixture
                            # check
                            if any(col.lower() == 'mixture' for col in columns):
                                # loop through values
                                for i in range(len(values)):
                                    # mixture name
                                    mixture_name = values[i][1]

                                    # split mixture name
                                    mixture_name = mixture_name.split('|')
                                    # check
                                    if len(mixture_name) != 2:
                                        raise Exception(
                                            f"Table data is None for {file_name}.")
                                    # strip keys
                                    mixture_name = [i.strip()
                                                    for i in mixture_name]
                                    # std key format
                                    mixture_name = f"{mixture_name[0]} | {mixture_name[1]}"
                                    # update values
                                    values[i][1] = mixture_name

                            values_ = [*values]

                            # NOTE: add to file data
                            file_data = []
                            # ! add to dataframe header
                            # file_data.append(columns)
                            file_data.append(symbol)
                            file_data.append(unit)
                            file_data.extend(values_)

                    elif tb_type == TableTypes.EQUATIONS.value:
                        # ! equations

                        # check
                        if values is None:
                            raise Exception(
                                f"Table data is None for {file_name}.")

                        # NOTE: make file data
                        file_data = []
                        # ! add to dataframe header
                        # file_data.append(columns)
                        file_data.append(symbol)
                        file_data.append(unit)
                        file_data.extend(values)

            # SECTION
            # check
            if file_path is not None:
                # create dataframe
                return pd.read_csv(file_path)
            elif file_data is not None and file_item_data is None:
                # create dataframe
                return pd.DataFrame(file_data, columns=columns)
            elif file_item_data is not None and file_data is None:
                # create dataframe
                # return df_dict
                raise Exception(
                    f"Table data is None for {file_name}.")
            else:
                raise Exception(f"{file_name} does not exist.")

        except FileNotFoundError:
            raise FileNotFoundError(
                f"File {file_name} not found in {self.path}")
        except Exception as e:
            raise Exception(f"Table loading error {e}")

    def search_tables(
            self,
            databook_id: int,
            table_id: int,
            column_name: str | list[str],
            lookup: str | list[str],
            query: bool = False
    ) -> pd.DataFrame:
        """
        Search tables in this directory

        Parameters
        ----------
        databook_id : int
            databook id
        Parameters
        ----------
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str
            column name
        lookup : str
            value to look up for
        query : bool, optional
            if True, then use query method, by default False

        Returns
        -------
        result : pandas Series
            result of search
        """
        try:
            # table type
            tb_type = self.get_table_type(databook_id, table_id)

            # dataframe
            df = None

            # check tb_type
            if (
                tb_type == TableTypes.DATA.value or
                tb_type == TableTypes.EQUATIONS.value
            ):
                # ! search table
                df = self.search_table(
                    databook_id,
                    table_id,
                    column_name,
                    lookup,
                    query=query
                )
            elif (
                tb_type == TableTypes.MATRIX_DATA.value or
                tb_type == TableTypes.MATRIX_EQUATIONS.value
            ):
                # ! search matrix table
                df = self.search_matrix_table(
                    databook_id,
                    table_id,
                    column_name,
                    lookup,
                    query=query
                )
            else:
                raise Exception(f"Table type {tb_type} is not supported.")

            return df
        except Exception as e:
            raise Exception(f"Table searching error {e}")

    def search_table(
        self,
        databook_id: int,
        table_id: int,
        column_name: str | list,
        lookup: str | list[str],
        query: bool = False
    ) -> pd.DataFrame:
        '''
        Search inside csv file which is converted to pandas dataframe

        Parameters
        ----------
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str | list
            column name
        lookup : str
            value to look up for

        Returns
        -------
        result : pandas DataFrame
            result of search
        '''
        try:
            # SECTION: tb
            # NOTE: load table data/equations (all data)
            df = self.load_table(databook_id, table_id)

            # NOTE: check dataframe
            if isinstance(df, pd.DataFrame):
                # take first three rows
                df_info = df.iloc[:2, :]

                # SECTION: filter
                if (
                    isinstance(column_name, str) and
                    query is False
                ):  # ! search by column name
                    # NOTE: check query
                    # create filter
                    # check lookup
                    if not isinstance(lookup, str):
                        raise ValueError(
                            f"Lookup value must be a string for {databook_id} and {table_id}."
                        )

                    df_filter = df[
                        df[column_name].str.lower() == lookup.lower()
                    ]
                elif (
                    isinstance(column_name, str) and
                    query is True
                ):  # ! search by query
                    # NOTE: check query
                    # create filter
                    df_filter = df.query(column_name, engine='python')

                elif (
                    isinstance(column_name, list) and
                    isinstance(lookup, list) and
                    query is False
                ):  # ! search by list of column names
                    # NOTE: check column names
                    if len(column_name) != len(lookup):
                        raise ValueError(
                            f"Column name and lookup must have the same length for {databook_id} and {table_id}."
                        )

                    # SECTION: use query
                    # use query
                    _query = []

                    # iterate through column names
                    for i in range(len(column_name)):
                        _query.append(
                            f'{column_name[i]}.str.lower() == "{str(lookup[i]).lower()}"'
                        )

                    # make query
                    _query_set = ' and '.join(_query)

                    # NOTE: query
                    df_filter = df.query(_query_set, engine='python')
                else:
                    raise ValueError(
                        f"Column name and lookup formats are not valid for {databook_id} and {table_id}."
                    )

                # SECTION: combine dfs
                result = pd.concat([df_info, df_filter])

                # NOTE: check
                if not df_filter.empty:
                    return result
                else:
                    return pd.DataFrame()
            else:
                raise Exception(
                    f"Table data is not a pandas dataframe for {databook_id} and {table_id}.")
        except Exception as e:
            raise Exception(f"Searching table error {e}")

    def search_matrix_table(
        self,
        databook_id: int,
        table_id: int,
        column_name: str | list[str],
        lookup: str | list[str],
        query: bool = False
    ) -> pd.DataFrame:
        '''
        Search inside csv file which is converted to pandas dataframe

        Parameters
        ----------
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str
            column name
        lookup : str
            value to look up for
        query : bool, optional
            if True, then use query method, by default False

        Returns
        -------
        result : pandas Series
            result of search
        '''
        # NOTE: load tb
        df = self.load_table(databook_id, table_id)

        # NOTE: search mode
        search_mode = False

        # NOTE: check dataframe
        if isinstance(df, pd.DataFrame):
            # NOTE: search matrix table
            # filter
            if (
                isinstance(column_name, str) and
                isinstance(lookup, str) and
                    query is False
            ):
                # create filter
                df_filter = df[df[column_name].str.lower() == lookup.lower()]
            if (
                isinstance(column_name, str) and
                    isinstance(lookup, list)
            ):
                # create filter
                # df_filter = df[df[column_name].isin(lookup)]

                # set
                search_mode = True

                lookup_normalized = [str(x).strip().lower() for x in lookup]
                df_filter = df[df[column_name].str.strip(
                ).str.lower().isin(lookup_normalized)]
            # query
            elif (
                isinstance(column_name, str) and
                query is True
            ):
                # create filter
                df_filter = df.query(column_name)
            # list
            elif (
                isinstance(column_name, list) and
                isinstance(lookup, list)
            ):
                # use query
                _queries = []
                for i in range(len(column_name)):
                    _queries.append(f'`{column_name[i]}` == "{lookup[i]}"')
                # make query
                _query_set = ' & '.join(_queries)
                # query
                df_filter = df.query(_query_set)
            # else:
            #     raise ValueError(
            #         f"Column name and lookup formats are not valid.")

            # NOTE: df_filter analysis
            # check if df_filter is empty
            if df_filter.empty:
                # raise exception
                raise Exception(
                    f"No data found for {databook_id} and {table_id} with column name {column_name} and lookup {lookup}.")

            # records number
            records_number = df_filter.shape[0]

            # FIXME: take first three rows
            if records_number == 2 and search_mode == False:
                df_info = df.iloc[:4, :]
            elif records_number == 2 and search_mode == True:
                # empty df_info
                df_info = pd.DataFrame(columns=df.columns)
            elif records_number == 4:
                df_info = df.iloc[:2, :]
            else:
                df_info = df.iloc[:4, :]

            # NOTE: combine dfs
            result = pd.concat([df_info, df_filter])

            # NOTE: check
            if not df_filter.empty:
                return result
            else:
                return pd.DataFrame()
        else:
            raise Exception(
                f"Table data is not a pandas dataframe for {databook_id} and {table_id}.")

    def make_payload(
        self,
        databook_id: int,
        table_id: int,
        column_name: str | list[str],
        lookup: str | list[str],
        query: bool = False,
        matrix_tb: bool = False
    ) -> PayLoadType | None:
        '''
        Make standard data

        Parameters
        ----------
        databook_id : int
            databook id
        table_id : int
            table id
        column_name : str
            column name
        lookup : str
            value to look up for

        Returns
        -------
        payload : PayLoadType | None
            standard data

        Notes
        -----
        header: list
            header
        symbol: list
            symbol
        unit: list
            unit
        records: list
            records, if nan exists then converted to 0
        '''
        try:
            # table type
            tb_type = self.get_table_type(databook_id, table_id)

            # SECTION: check
            if matrix_tb:
                df = self.search_matrix_table(
                    databook_id,
                    table_id,
                    column_name,
                    lookup=lookup,
                    query=query
                )
            else:
                df = self.search_table(
                    databook_id,
                    table_id,
                    column_name,
                    lookup=lookup,
                    query=query
                )

            # SECTION: check
            if len(df) > 0:
                # payload
                if matrix_tb:
                    records_clean = df.iloc[4, :].fillna(0).to_list()
                else:
                    records_clean = df.iloc[2, :].fillna(0).to_list()

                # payload
                payload: PayLoadType = {
                    "header": df.columns.to_list(),
                    "symbol": df.iloc[0, :].to_list(),
                    "unit": df.iloc[1, :].to_list(),
                    "records": records_clean,
                }

                # res
                return payload
            else:
                return None

        except Exception as e:
            raise Exception(f"Making payload error {e}")

    def search_component(
        self,
        search_terms: list[str],
        search_mode: str,
        column_names: list[str] = ['Name', 'Formula']
    ) -> list[dict]:
        """
        Search a component in all databooks

        Parameters
        ----------
        column_names : list
            the list of column names (default: ['Name', 'Formula'])
        search_terms : list[str]
            search terms for instance a component name or formula

        """
        try:
            # data path
            directory = self.path

            # Initialize an empty list to store results
            results = []

            # Get a list of all CSV files in the directory
            csv_files = glob.glob(directory + '/*.csv')

            # Capitalize the search terms
            search_terms = [term.upper() for term in search_terms]

            # Iterate over each CSV file
            for file in csv_files:
                try:
                    # Read the CSV file
                    df = pd.read_csv(file)

                    # Get existing column names
                    existing_columns = [col for col in column_names if col.lower() in [
                        c.lower() for c in df.columns]]

                    # Skip if no columns exist
                    if not existing_columns:
                        # print(f"No matching columns found in {file}.")
                        continue

                    # Convert existing columns to string and capitalize
                    for col in existing_columns:
                        df[col] = df[col].apply(lambda x: str(x).upper())

                    # Filter rows where any existing column matches the search term(s)
                    if len(search_terms) == 1:
                        # Search both columns with single term
                        # check search mode
                        if search_mode == 'similar':
                            matching_rows = df[df[existing_columns].apply(
                                lambda x: x.str.contains(search_terms[0])).any(axis=1)]
                        elif search_mode == 'exact':
                            matching_rows = df[df[existing_columns].eq(
                                search_terms[0]).any(axis=1)]
                        else:
                            raise ValueError(
                                f"Invalid search mode: {search_mode}")
                    else:
                        # Search specific columns with multiple terms
                        if len(existing_columns) < 2:
                            # print(f"Only one matching column found in {file}.")
                            # check search mode
                            if search_mode == 'similar':
                                matching_rows = df[df[existing_columns[0]
                                                      ].str.contains(search_terms[0])]
                            elif search_mode == 'exact':
                                matching_rows = df[df[existing_columns[0]].eq(
                                    search_terms[0])]
                            else:
                                raise ValueError(
                                    f"Invalid search mode: {search_mode}")
                        else:
                            # check search mode
                            if search_mode == 'similar':
                                matching_rows = df[
                                    (df[existing_columns[0]].str.contains(search_terms[0])) |
                                    (df[existing_columns[1]].str.contains(
                                        search_terms[1]))
                                ]
                            elif search_mode == 'exact':
                                matching_rows = df[
                                    (df[existing_columns[0]].eq(search_terms[0])) &
                                    (df[existing_columns[1]].eq(search_terms[1]))
                                ]

                            else:
                                raise ValueError(
                                    f"Invalid search mode: {search_mode}")

                    # Add results to the list if matches are found
                    if not matching_rows.empty:
                        # csv file
                        # _csv_file = file.split('/')[-1]
                        # csv file
                        _csv_file = os.path.basename(file)
                        # csv file name
                        _table_name, extension = os.path.splitext(_csv_file)
                        # get source
                        _get_source = self.find_table_source(_table_name)
                        # check
                        if not _get_source:
                            raise Exception(
                                f"Source not found for {_table_name}")

                        # source (non-zero-based id)
                        db, db_id, tb_name, tb_id, data_type = _get_source.values()

                        # table-description
                        table_description = self.get_table(db, tb_name)[
                            'description']

                        # save
                        results.append({
                            'search-mode': search_mode,
                            'search-terms': ', '.join(search_terms),
                            'databook-id': db_id,
                            'databook-name': db,
                            'table-id': tb_id,
                            'table-name': _table_name,
                            'table-description': table_description,
                            'data-type': data_type,
                        })
                except pd.errors.EmptyDataError:
                    print(f"{file} is empty.")
                except pd.errors.ParserError:
                    print(f"Error parsing {file}.")

            return results

        except Exception as e:
            raise Exception(f'Searching component error {e}')

    def list_all_components(
        self,
        column_name: str = 'Name'
    ) -> tuple[list[str], list[dict[str, str | int]]]:
        """
        List all components in all databooks.

        Returns
        -------
        components : list
            list of components
        components_info : list
            list of component information
        """
        try:
            # get all components
            components = []
            # component info
            components_info = []

            # data path
            directory = self.path

            # Get a list of all CSV files in the directory
            csv_files = glob.glob(directory + '/*.csv')

            # Iterate over each CSV file
            for file in csv_files:
                # read
                df = pd.read_csv(file)

                # get columns
                columns = df.columns.tolist()

                # check
                if len(columns) > 1:
                    # check column name
                    if column_name in columns:
                        # get component
                        component = df[column_name].tolist()

                        # csv file
                        _csv_file = os.path.basename(file)
                        # csv file name
                        _table_name, extension = os.path.splitext(_csv_file)
                        # get source
                        _get_source = self.find_table_source(_table_name)
                        # check
                        if not _get_source:
                            raise Exception(
                                f"Source not found for {_table_name}")

                        # source
                        db, db_id, tb_name, tb_id, data_type = _get_source.values()

                        # add to list
                        components.extend(component)

                        # component info
                        component_info = {
                            "component": component,
                            "databook": db,
                            "database_id": db_id,
                            "table_name": tb_name,
                            "table_id": tb_id,
                            "data_type": data_type
                        }
                        components_info.append(component_info)

            return components, components_info

        except Exception as e:
            raise Exception(f'Listing all components error {e}')

    def retrieve_data(
            self,
            table_data: DataBookTableTypes,
            table_type: str):
        '''
        Retrieve data from table data based on table type

        Parameters
        ----------
        table_data : Dict
            table data
        table_type : str
            table type
                - data
                - equations
                - matrix-data
                - matrix-equations

        Returns
        -------
        data : list
            data
        '''
        try:
            # check table type
            if table_type == TableTypes.DATA.value:
                # data
                data = table_data['data']
            elif table_type == TableTypes.EQUATIONS.value:
                # data
                data = table_data['equations']
            elif table_type == TableTypes.MATRIX_DATA.value:
                # data
                data = table_data['matrix_data']
            elif table_type == TableTypes.MATRIX_EQUATIONS.value:
                # data
                data = table_data['matrix_equations']
            else:
                raise Exception(f"Table type {table_type} is not supported.")

            # check
            if data is None:
                raise Exception(f"Table data is None.")

            # res
            return data
        except Exception as e:
            raise Exception(f"Retrieving data error {e}")

list_all_components(column_name='Name')

List all components in all databooks.

Returns

components : list list of components components_info : list list of component information

Source code in pyThermoDB/docs/tableref.py

def list_all_components(
    self,
    column_name: str = 'Name'
) -> tuple[list[str], list[dict[str, str | int]]]:
    """
    List all components in all databooks.

    Returns
    -------
    components : list
        list of components
    components_info : list
        list of component information
    """
    try:
        # get all components
        components = []
        # component info
        components_info = []

        # data path
        directory = self.path

        # Get a list of all CSV files in the directory
        csv_files = glob.glob(directory + '/*.csv')

        # Iterate over each CSV file
        for file in csv_files:
            # read
            df = pd.read_csv(file)

            # get columns
            columns = df.columns.tolist()

            # check
            if len(columns) > 1:
                # check column name
                if column_name in columns:
                    # get component
                    component = df[column_name].tolist()

                    # csv file
                    _csv_file = os.path.basename(file)
                    # csv file name
                    _table_name, extension = os.path.splitext(_csv_file)
                    # get source
                    _get_source = self.find_table_source(_table_name)
                    # check
                    if not _get_source:
                        raise Exception(
                            f"Source not found for {_table_name}")

                    # source
                    db, db_id, tb_name, tb_id, data_type = _get_source.values()

                    # add to list
                    components.extend(component)

                    # component info
                    component_info = {
                        "component": component,
                        "databook": db,
                        "database_id": db_id,
                        "table_name": tb_name,
                        "table_id": tb_id,
                        "data_type": data_type
                    }
                    components_info.append(component_info)

        return components, components_info

    except Exception as e:
        raise Exception(f'Listing all components error {e}')

list_databooks()

list databooks

Source code in pyThermoDB/docs/tableref.py

def list_databooks(self):
    '''
    list databooks
    '''
    _, df, _ = self.get_databooks()
    return df

list_tables(databook, res_format='dataframe')

List all tables in the selected databook

Parameters

databook : int | str databook id or name res_format : Literal['list', 'dataframe', 'json'] Format of the returned data. Defaults to 'dataframe'.

Returns

table list : list | pandas.DataFrame | str | dict[str, str] list of tables

Source code in pyThermoDB/docs/tableref.py

def list_tables(
    self,
    databook: int | str,
    res_format: Literal[
        'list', 'dataframe', 'json', 'dict'
    ] = 'dataframe'
) -> list[list[str]] | pd.DataFrame | str | dict[str, str]:
    '''
    List all tables in the selected databook

    Parameters
    ----------
    databook : int | str
        databook id or name
    res_format : Literal['list', 'dataframe', 'json']
        Format of the returned data. Defaults to 'dataframe'.

    Returns
    -------
    table list : list | pandas.DataFrame | str | dict[str, str]
        list of tables
    '''
    try:
        # manual databook setting
        db, db_name, db_id = self.find_databook(databook)
        # table list
        res = self.get_tables(db_name)
        # check
        if res_format == 'list':
            return res[0]
        elif res_format == 'dataframe':
            return res[1]
        elif res_format == 'json':
            return res[2]
        elif res_format == 'dict':
            return res[3]
        else:
            raise ValueError('Invalid res_format')
    except Exception as e:
        raise Exception("Table loading error!,", e)

load_external_csv(custom_ref)

Load external csv file paths

Parameters

custom_ref : CustomRef custom ref

Source code in pyThermoDB/docs/tableref.py

def load_external_csv(self, custom_ref: CustomRef) -> list[str]:
    '''
    Load external csv file paths

    Parameters
    ----------
    custom_ref : CustomRef
        custom ref
    '''
    path_external = custom_ref.csv_paths
    return path_external

load_table(databook_id, table_id)

Load a csv file from app directory or external reference and convert it to a pandas dataframe. If the table is a matrix data, it will return a dictionary of dataframes. If the table is a data or equations, it will return a single dataframe.

Parameters

databook_id : int databook id (non-zero-based id) table_id : int table id (non-zero-based id)

Returns

pandas DataFrame pandas DataFrame

Source code in pyThermoDB/docs/tableref.py

def load_table(
    self,
    databook_id: int,
    table_id: int
) -> pd.DataFrame:
    """
    Load a `csv file` from app directory or external reference
    and convert it to a pandas dataframe.
    If the table is a matrix data, it will return a dictionary of dataframes.
    If the table is a data or equations, it will return a single dataframe.

    Parameters
    ----------
    databook_id : int
        databook id (non-zero-based id)
    table_id : int
        table id (non-zero-based id)

    Returns
    -------
    pandas DataFrame
        pandas DataFrame
    """
    try:
        # init vars
        file_data = None
        file_item_data = None
        file_path = None

        # NOTE:
        # table
        tb = self.get_table(databook_id-1, table_id-1)
        # table type
        tb_type = tb['table_type']

        # table name
        table_name = tb['table']
        # table file
        file_name = table_name + '.csv'

        # check table exists in local or external references
        reference_local_no = self.reference_local_no

        # SECTION: table file path
        # local
        if databook_id <= reference_local_no:
            # set file path
            file_path = os.path.join(self.path, file_name)
        else:
            # check
            if self.custom_ref is None:
                raise ValueError('No custom reference provided')

            # NOTE: load external path
            path_external = self.load_external_csv(self.custom_ref)

            # SECTION: check if the file exists in the external paths
            file_path = None
            # check
            if len(path_external) > 0:
                # check csv paths
                # csv file names
                file_names = [
                    os.path.basename(path) for path in path_external
                ]
                # check csv file
                for item in file_names:
                    if item == file_name:
                        file_path = path_external[file_names.index(item)]
                        break

            # SECTION: load values from custom reference (if exists in the yml/md file)
            # ! check both yml and md files
            if tb_type and file_path is None:
                # load table data
                table_data = self.retrieve_data(
                    tb, tb_type)

                # NOTE: load structure
                table_structure = tb.get('table_structure', None)

                # check
                if table_structure is None:
                    raise Exception(
                        f"Table data is None for {file_name}.")

                # NOTE: table structure
                columns = table_structure.get('COLUMNS', None)
                symbol = table_structure.get('SYMBOL', None)
                unit = table_structure.get('UNIT', None)

                # check
                if columns is None or symbol is None or unit is None:
                    raise Exception(
                        f"Table data is None for {file_name}.")

                # SECTION: used by matrix data
                # NOTE: table_values
                values = tb.get('table_values', None)
                # NOTE: table_items
                items = tb.get('table_items', None)

                # NOTE: load values
                if tb_type == TableTypes.DATA.value:
                    # ! data & matrix data

                    # check
                    if values is None:
                        raise Exception(
                            f"Table data is None for {file_name}.")

                    # NOTE: add to file data
                    file_data = []
                    # ! add to dataframe header
                    # file_data.append(columns)
                    file_data.append(symbol)
                    file_data.append(unit)
                    file_data.extend(values)

                elif tb_type == TableTypes.MATRIX_DATA.value:
                    # ! matrix data

                    # NOTE: values or items
                    # check
                    if values is None:
                        # check items
                        if items is None:
                            # ! raise exception as no values or items
                            raise Exception(
                                f"Table data is None for {file_name}.")

                    # NOTE: matrix data
                    matrix_data = tb.get('matrix_data', None)
                    # check
                    if matrix_data is None:
                        raise Exception(
                            f"Table data is None for {file_name}.")

                    # matrix symbol
                    matrix_symbol = matrix_data.get('MATRIX-SYMBOL', None)

                    # check
                    if matrix_symbol is None:
                        raise Exception(
                            f"Table data is None for {file_name}.")

                    # size of matrix symbols
                    matrix_symbol_len = len(matrix_symbol)

                    # SECTION: values
                    if values and isinstance(values, list):
                        # # size of matrix symbols
                        # component_idx_len = len(values) - 2

                        # # ! No., Name, Formula are necessary for matrix data
                        # header_ = ['None', 'None', 'None']
                        # component_idx = [str(i) for i in range(
                        #     1, component_idx_len+1)]*matrix_symbol_len

                        # # updated header
                        # header_ = header_ + component_idx

                        # # updated values
                        # values_ = [header_, *values]
                        # NOTE: check columns contains Mixture
                        # check
                        if any(col.lower() == 'mixture' for col in columns):
                            # loop through values
                            for i in range(len(values)):
                                # mixture name
                                mixture_name = values[i][1]

                                # split mixture name
                                mixture_name = mixture_name.split('|')
                                # check
                                if len(mixture_name) != 2:
                                    raise Exception(
                                        f"Table data is None for {file_name}.")
                                # strip keys
                                mixture_name = [i.strip()
                                                for i in mixture_name]
                                # std key format
                                mixture_name = f"{mixture_name[0]} | {mixture_name[1]}"
                                # update values
                                values[i][1] = mixture_name

                        values_ = [*values]

                        # NOTE: add to file data
                        file_data = []
                        # ! add to dataframe header
                        # file_data.append(columns)
                        file_data.append(symbol)
                        file_data.append(unit)
                        file_data.extend(values_)

                elif tb_type == TableTypes.EQUATIONS.value:
                    # ! equations

                    # check
                    if values is None:
                        raise Exception(
                            f"Table data is None for {file_name}.")

                    # NOTE: make file data
                    file_data = []
                    # ! add to dataframe header
                    # file_data.append(columns)
                    file_data.append(symbol)
                    file_data.append(unit)
                    file_data.extend(values)

        # SECTION
        # check
        if file_path is not None:
            # create dataframe
            return pd.read_csv(file_path)
        elif file_data is not None and file_item_data is None:
            # create dataframe
            return pd.DataFrame(file_data, columns=columns)
        elif file_item_data is not None and file_data is None:
            # create dataframe
            # return df_dict
            raise Exception(
                f"Table data is None for {file_name}.")
        else:
            raise Exception(f"{file_name} does not exist.")

    except FileNotFoundError:
        raise FileNotFoundError(
            f"File {file_name} not found in {self.path}")
    except Exception as e:
        raise Exception(f"Table loading error {e}")

make_payload(databook_id, table_id, column_name, lookup, query=False, matrix_tb=False)

Make standard data

Parameters

databook_id : int databook id table_id : int table id column_name : str column name lookup : str value to look up for

Returns

payload : PayLoadType | None standard data

Notes

header: list header symbol: list symbol unit: list unit records: list records, if nan exists then converted to 0

Source code in pyThermoDB/docs/tableref.py

def make_payload(
    self,
    databook_id: int,
    table_id: int,
    column_name: str | list[str],
    lookup: str | list[str],
    query: bool = False,
    matrix_tb: bool = False
) -> PayLoadType | None:
    '''
    Make standard data

    Parameters
    ----------
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str
        column name
    lookup : str
        value to look up for

    Returns
    -------
    payload : PayLoadType | None
        standard data

    Notes
    -----
    header: list
        header
    symbol: list
        symbol
    unit: list
        unit
    records: list
        records, if nan exists then converted to 0
    '''
    try:
        # table type
        tb_type = self.get_table_type(databook_id, table_id)

        # SECTION: check
        if matrix_tb:
            df = self.search_matrix_table(
                databook_id,
                table_id,
                column_name,
                lookup=lookup,
                query=query
            )
        else:
            df = self.search_table(
                databook_id,
                table_id,
                column_name,
                lookup=lookup,
                query=query
            )

        # SECTION: check
        if len(df) > 0:
            # payload
            if matrix_tb:
                records_clean = df.iloc[4, :].fillna(0).to_list()
            else:
                records_clean = df.iloc[2, :].fillna(0).to_list()

            # payload
            payload: PayLoadType = {
                "header": df.columns.to_list(),
                "symbol": df.iloc[0, :].to_list(),
                "unit": df.iloc[1, :].to_list(),
                "records": records_clean,
            }

            # res
            return payload
        else:
            return None

    except Exception as e:
        raise Exception(f"Making payload error {e}")

retrieve_data(table_data, table_type)

Retrieve data from table data based on table type

Parameters

table_data : Dict table data table_type : str table type - data - equations - matrix-data - matrix-equations

Returns

data : list data

Source code in pyThermoDB/docs/tableref.py

def retrieve_data(
        self,
        table_data: DataBookTableTypes,
        table_type: str):
    '''
    Retrieve data from table data based on table type

    Parameters
    ----------
    table_data : Dict
        table data
    table_type : str
        table type
            - data
            - equations
            - matrix-data
            - matrix-equations

    Returns
    -------
    data : list
        data
    '''
    try:
        # check table type
        if table_type == TableTypes.DATA.value:
            # data
            data = table_data['data']
        elif table_type == TableTypes.EQUATIONS.value:
            # data
            data = table_data['equations']
        elif table_type == TableTypes.MATRIX_DATA.value:
            # data
            data = table_data['matrix_data']
        elif table_type == TableTypes.MATRIX_EQUATIONS.value:
            # data
            data = table_data['matrix_equations']
        else:
            raise Exception(f"Table type {table_type} is not supported.")

        # check
        if data is None:
            raise Exception(f"Table data is None.")

        # res
        return data
    except Exception as e:
        raise Exception(f"Retrieving data error {e}")

search_component(search_terms, search_mode, column_names=['Name', 'Formula'])

Search a component in all databooks

Parameters

column_names : list the list of column names (default: ['Name', 'Formula']) search_terms : list[str] search terms for instance a component name or formula

Source code in pyThermoDB/docs/tableref.py

def search_component(
    self,
    search_terms: list[str],
    search_mode: str,
    column_names: list[str] = ['Name', 'Formula']
) -> list[dict]:
    """
    Search a component in all databooks

    Parameters
    ----------
    column_names : list
        the list of column names (default: ['Name', 'Formula'])
    search_terms : list[str]
        search terms for instance a component name or formula

    """
    try:
        # data path
        directory = self.path

        # Initialize an empty list to store results
        results = []

        # Get a list of all CSV files in the directory
        csv_files = glob.glob(directory + '/*.csv')

        # Capitalize the search terms
        search_terms = [term.upper() for term in search_terms]

        # Iterate over each CSV file
        for file in csv_files:
            try:
                # Read the CSV file
                df = pd.read_csv(file)

                # Get existing column names
                existing_columns = [col for col in column_names if col.lower() in [
                    c.lower() for c in df.columns]]

                # Skip if no columns exist
                if not existing_columns:
                    # print(f"No matching columns found in {file}.")
                    continue

                # Convert existing columns to string and capitalize
                for col in existing_columns:
                    df[col] = df[col].apply(lambda x: str(x).upper())

                # Filter rows where any existing column matches the search term(s)
                if len(search_terms) == 1:
                    # Search both columns with single term
                    # check search mode
                    if search_mode == 'similar':
                        matching_rows = df[df[existing_columns].apply(
                            lambda x: x.str.contains(search_terms[0])).any(axis=1)]
                    elif search_mode == 'exact':
                        matching_rows = df[df[existing_columns].eq(
                            search_terms[0]).any(axis=1)]
                    else:
                        raise ValueError(
                            f"Invalid search mode: {search_mode}")
                else:
                    # Search specific columns with multiple terms
                    if len(existing_columns) < 2:
                        # print(f"Only one matching column found in {file}.")
                        # check search mode
                        if search_mode == 'similar':
                            matching_rows = df[df[existing_columns[0]
                                                  ].str.contains(search_terms[0])]
                        elif search_mode == 'exact':
                            matching_rows = df[df[existing_columns[0]].eq(
                                search_terms[0])]
                        else:
                            raise ValueError(
                                f"Invalid search mode: {search_mode}")
                    else:
                        # check search mode
                        if search_mode == 'similar':
                            matching_rows = df[
                                (df[existing_columns[0]].str.contains(search_terms[0])) |
                                (df[existing_columns[1]].str.contains(
                                    search_terms[1]))
                            ]
                        elif search_mode == 'exact':
                            matching_rows = df[
                                (df[existing_columns[0]].eq(search_terms[0])) &
                                (df[existing_columns[1]].eq(search_terms[1]))
                            ]

                        else:
                            raise ValueError(
                                f"Invalid search mode: {search_mode}")

                # Add results to the list if matches are found
                if not matching_rows.empty:
                    # csv file
                    # _csv_file = file.split('/')[-1]
                    # csv file
                    _csv_file = os.path.basename(file)
                    # csv file name
                    _table_name, extension = os.path.splitext(_csv_file)
                    # get source
                    _get_source = self.find_table_source(_table_name)
                    # check
                    if not _get_source:
                        raise Exception(
                            f"Source not found for {_table_name}")

                    # source (non-zero-based id)
                    db, db_id, tb_name, tb_id, data_type = _get_source.values()

                    # table-description
                    table_description = self.get_table(db, tb_name)[
                        'description']

                    # save
                    results.append({
                        'search-mode': search_mode,
                        'search-terms': ', '.join(search_terms),
                        'databook-id': db_id,
                        'databook-name': db,
                        'table-id': tb_id,
                        'table-name': _table_name,
                        'table-description': table_description,
                        'data-type': data_type,
                    })
            except pd.errors.EmptyDataError:
                print(f"{file} is empty.")
            except pd.errors.ParserError:
                print(f"Error parsing {file}.")

        return results

    except Exception as e:
        raise Exception(f'Searching component error {e}')

search_matrix_table(databook_id, table_id, column_name, lookup, query=False)

Search inside csv file which is converted to pandas dataframe

Parameters

databook_id : int databook id table_id : int table id column_name : str column name lookup : str value to look up for query : bool, optional if True, then use query method, by default False

Returns

result : pandas Series result of search

Source code in pyThermoDB/docs/tableref.py

def search_matrix_table(
    self,
    databook_id: int,
    table_id: int,
    column_name: str | list[str],
    lookup: str | list[str],
    query: bool = False
) -> pd.DataFrame:
    '''
    Search inside csv file which is converted to pandas dataframe

    Parameters
    ----------
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str
        column name
    lookup : str
        value to look up for
    query : bool, optional
        if True, then use query method, by default False

    Returns
    -------
    result : pandas Series
        result of search
    '''
    # NOTE: load tb
    df = self.load_table(databook_id, table_id)

    # NOTE: search mode
    search_mode = False

    # NOTE: check dataframe
    if isinstance(df, pd.DataFrame):
        # NOTE: search matrix table
        # filter
        if (
            isinstance(column_name, str) and
            isinstance(lookup, str) and
                query is False
        ):
            # create filter
            df_filter = df[df[column_name].str.lower() == lookup.lower()]
        if (
            isinstance(column_name, str) and
                isinstance(lookup, list)
        ):
            # create filter
            # df_filter = df[df[column_name].isin(lookup)]

            # set
            search_mode = True

            lookup_normalized = [str(x).strip().lower() for x in lookup]
            df_filter = df[df[column_name].str.strip(
            ).str.lower().isin(lookup_normalized)]
        # query
        elif (
            isinstance(column_name, str) and
            query is True
        ):
            # create filter
            df_filter = df.query(column_name)
        # list
        elif (
            isinstance(column_name, list) and
            isinstance(lookup, list)
        ):
            # use query
            _queries = []
            for i in range(len(column_name)):
                _queries.append(f'`{column_name[i]}` == "{lookup[i]}"')
            # make query
            _query_set = ' & '.join(_queries)
            # query
            df_filter = df.query(_query_set)
        # else:
        #     raise ValueError(
        #         f"Column name and lookup formats are not valid.")

        # NOTE: df_filter analysis
        # check if df_filter is empty
        if df_filter.empty:
            # raise exception
            raise Exception(
                f"No data found for {databook_id} and {table_id} with column name {column_name} and lookup {lookup}.")

        # records number
        records_number = df_filter.shape[0]

        # FIXME: take first three rows
        if records_number == 2 and search_mode == False:
            df_info = df.iloc[:4, :]
        elif records_number == 2 and search_mode == True:
            # empty df_info
            df_info = pd.DataFrame(columns=df.columns)
        elif records_number == 4:
            df_info = df.iloc[:2, :]
        else:
            df_info = df.iloc[:4, :]

        # NOTE: combine dfs
        result = pd.concat([df_info, df_filter])

        # NOTE: check
        if not df_filter.empty:
            return result
        else:
            return pd.DataFrame()
    else:
        raise Exception(
            f"Table data is not a pandas dataframe for {databook_id} and {table_id}.")

search_table(databook_id, table_id, column_name, lookup, query=False)

Search inside csv file which is converted to pandas dataframe

Parameters

databook_id : int databook id table_id : int table id column_name : str | list column name lookup : str value to look up for

Returns

result : pandas DataFrame result of search

Source code in pyThermoDB/docs/tableref.py

def search_table(
    self,
    databook_id: int,
    table_id: int,
    column_name: str | list,
    lookup: str | list[str],
    query: bool = False
) -> pd.DataFrame:
    '''
    Search inside csv file which is converted to pandas dataframe

    Parameters
    ----------
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str | list
        column name
    lookup : str
        value to look up for

    Returns
    -------
    result : pandas DataFrame
        result of search
    '''
    try:
        # SECTION: tb
        # NOTE: load table data/equations (all data)
        df = self.load_table(databook_id, table_id)

        # NOTE: check dataframe
        if isinstance(df, pd.DataFrame):
            # take first three rows
            df_info = df.iloc[:2, :]

            # SECTION: filter
            if (
                isinstance(column_name, str) and
                query is False
            ):  # ! search by column name
                # NOTE: check query
                # create filter
                # check lookup
                if not isinstance(lookup, str):
                    raise ValueError(
                        f"Lookup value must be a string for {databook_id} and {table_id}."
                    )

                df_filter = df[
                    df[column_name].str.lower() == lookup.lower()
                ]
            elif (
                isinstance(column_name, str) and
                query is True
            ):  # ! search by query
                # NOTE: check query
                # create filter
                df_filter = df.query(column_name, engine='python')

            elif (
                isinstance(column_name, list) and
                isinstance(lookup, list) and
                query is False
            ):  # ! search by list of column names
                # NOTE: check column names
                if len(column_name) != len(lookup):
                    raise ValueError(
                        f"Column name and lookup must have the same length for {databook_id} and {table_id}."
                    )

                # SECTION: use query
                # use query
                _query = []

                # iterate through column names
                for i in range(len(column_name)):
                    _query.append(
                        f'{column_name[i]}.str.lower() == "{str(lookup[i]).lower()}"'
                    )

                # make query
                _query_set = ' and '.join(_query)

                # NOTE: query
                df_filter = df.query(_query_set, engine='python')
            else:
                raise ValueError(
                    f"Column name and lookup formats are not valid for {databook_id} and {table_id}."
                )

            # SECTION: combine dfs
            result = pd.concat([df_info, df_filter])

            # NOTE: check
            if not df_filter.empty:
                return result
            else:
                return pd.DataFrame()
        else:
            raise Exception(
                f"Table data is not a pandas dataframe for {databook_id} and {table_id}.")
    except Exception as e:
        raise Exception(f"Searching table error {e}")

search_tables(databook_id, table_id, column_name, lookup, query=False)

Search tables in this directory

Parameters

databook_id : int databook id Parameters

---

databook_id : int databook id table_id : int table id column_name : str column name lookup : str value to look up for query : bool, optional if True, then use query method, by default False

Returns

result : pandas Series result of search

Source code in pyThermoDB/docs/tableref.py

def search_tables(
        self,
        databook_id: int,
        table_id: int,
        column_name: str | list[str],
        lookup: str | list[str],
        query: bool = False
) -> pd.DataFrame:
    """
    Search tables in this directory

    Parameters
    ----------
    databook_id : int
        databook id
    Parameters
    ----------
    databook_id : int
        databook id
    table_id : int
        table id
    column_name : str
        column name
    lookup : str
        value to look up for
    query : bool, optional
        if True, then use query method, by default False

    Returns
    -------
    result : pandas Series
        result of search
    """
    try:
        # table type
        tb_type = self.get_table_type(databook_id, table_id)

        # dataframe
        df = None

        # check tb_type
        if (
            tb_type == TableTypes.DATA.value or
            tb_type == TableTypes.EQUATIONS.value
        ):
            # ! search table
            df = self.search_table(
                databook_id,
                table_id,
                column_name,
                lookup,
                query=query
            )
        elif (
            tb_type == TableTypes.MATRIX_DATA.value or
            tb_type == TableTypes.MATRIX_EQUATIONS.value
        ):
            # ! search matrix table
            df = self.search_matrix_table(
                databook_id,
                table_id,
                column_name,
                lookup,
                query=query
            )
        else:
            raise Exception(f"Table type {tb_type} is not supported.")

        return df
    except Exception as e:
        raise Exception(f"Table searching error {e}")

transdata

TransData

Transform class

Source code in pyThermoDB/transformer/transdata.py

class TransData:
    '''
    Transform class
    '''
    __data_type = ''

    def __init__(self, api_data):
        self.api_data = api_data
        self.data_trans = {}

    @property
    def data_type(self):
        return self.__data_type

    @data_type.setter
    def data_type(self, value):
        self.__data_type = value

    def trans(self):
        '''
        Transform the data loaded from API,
        It consists of:
            step 1: display api data
                data['header'],['records'],['unit']
            step 2: transform to dict
        '''
        self.data_trans = {}

        # loop through the data including header, records, unit, symbol
        for x, y, z, w in zip(self.api_data['header'], self.api_data['records'], self.api_data['unit'], self.api_data['symbol']):
            # check eq exists
            if x == "Eq":
                self.eq_id = y
                # set data type
                self.__data_type = 'equation'
            else:
                self.__data_type = 'data'

            # set values
            self.data_trans[str(x)] = {"value": y, "unit": z, "symbol": w}

        # data table
        self.data_trans['data'] = self.api_data
        return self.data_trans

    def view(self, value=False):
        '''
        Display data in a table (pandas dataframe)

        Parameters
        ----------
        value: bool
            display value

        Returns
        -------
        df: dataframe
            data table
        '''
        df = pd.DataFrame(self.api_data)
        print(df)
        # check
        if value:
            return df
        else:
            return None

trans()

Transform the data loaded from API, It consists of: step 1: display api data data['header'],['records'],['unit'] step 2: transform to dict

Source code in pyThermoDB/transformer/transdata.py

def trans(self):
    '''
    Transform the data loaded from API,
    It consists of:
        step 1: display api data
            data['header'],['records'],['unit']
        step 2: transform to dict
    '''
    self.data_trans = {}

    # loop through the data including header, records, unit, symbol
    for x, y, z, w in zip(self.api_data['header'], self.api_data['records'], self.api_data['unit'], self.api_data['symbol']):
        # check eq exists
        if x == "Eq":
            self.eq_id = y
            # set data type
            self.__data_type = 'equation'
        else:
            self.__data_type = 'data'

        # set values
        self.data_trans[str(x)] = {"value": y, "unit": z, "symbol": w}

    # data table
    self.data_trans['data'] = self.api_data
    return self.data_trans

view(value=False)

Display data in a table (pandas dataframe)

Parameters

value: bool display value

Returns

df: dataframe data table

Source code in pyThermoDB/transformer/transdata.py

def view(self, value=False):
    '''
    Display data in a table (pandas dataframe)

    Parameters
    ----------
    value: bool
        display value

    Returns
    -------
    df: dataframe
        data table
    '''
    df = pd.DataFrame(self.api_data)
    print(df)
    # check
    if value:
        return df
    else:
        return None

tableequation

TableEquation

Source code in pyThermoDB/core/tableequation.py

class TableEquation:
    # vars
    body = ''
    parms = {}
    args = {}
    arg_symbols = {}
    returns = {}
    return_symbols = {}
    _summary = {}
    body_integral = ''
    body_first_derivative = ''
    body_second_derivative = ''
    __trans_data = {}
    __prop_equation = {}
    __parms_values = {}
    # custom integral
    _custom_integral = {}
    # selected equation id
    eq_id: int = -1

    def __init__(
        self,
        databook_name,
        table_name,
        equations,
        table_values: Optional[List | Dict] = None,
        table_structure: Optional[Dict[str, Any]] = None
    ):
        '''
        Initialize the TableEquation class.

        Parameters
        ----------
        databook_name : str
            Name of the databook.
        table_name : str
            Name of the table.
        equations : list
            List of equations.
        table_values : list, optional
            Values for the table (default is None), if provided in yml file.
        table_structure : dict, optional
            Structure of the table (default is None), if provided in yml file.
        '''
        self.databook_name = databook_name
        self.table_name = table_name
        self.equations = equations  # equation list structures (yml file)
        # number of equations
        self.eq_num = len(equations)
        # table values (yml)
        self.__table_values = table_values if table_values else None
        # table structure (yml)
        self.__table_structure = table_structure if table_structure else None

    @property
    def trans_data(self):
        return self.__trans_data

    @trans_data.setter
    def trans_data(self, value):
        self.__trans_data = {}
        self.__trans_data = value

    @property
    def prop_equation(self):
        return self.__prop_equation

    @property
    def parms_values(self):
        return self.__parms_values

    @property
    def custom_integral(self):
        return self._custom_integral

    @property
    def summary(self):
        return {
            'databook_name': self.databook_name,
            'table_name': self.table_name,
            'eq_id': self.eq_id,
            'args': self.args,
            'arg_symbols': self.arg_symbols,
            'parms': self.parms,
            'returns': self.returns,
            'return_symbols': self.return_symbols,
            'body': self.body,
            'body_integral': self.body_integral,
            'body_first_derivative': self.body_first_derivative,
            'body_second_derivative': self.body_second_derivative,
            'custom_integral': self._custom_integral
        }

    @property
    def table_values(self):
        '''Get table values from yml file (if exists)'''
        if self.__table_values:
            return self.__table_values
        else:
            msg = f"""No table values found in the following reference \n
            ::: {self.databook_name}
            :::  {self.table_name}!
            """
            print(msg)
            return None

    @property
    def table_structure(self):
        '''Get table structure from yml file (if exists)'''
        if self.__table_structure:
            return self.__table_structure
        else:
            msg = f"""No table structure found in the following reference \n
            ::: {self.databook_name}
            :::  {self.table_name}!
            """
            print(msg)
            return None

    def eq_structure(self, id=1):
        '''
        Display equation details

        Parameters
        ----------
        id : int
            equation id (from 1 to ...), default is 1

        Returns
        -------
        eq_summary : dict
            equation summary
        '''
        try:
            # set id
            id = int(id)-1
            # equation id
            equation = self.equations[id]
            # equation body
            _body = equation['BODY']
            # equation args
            _args = equation['ARGS']
            # equation params
            _parms = equation['PARMS']
            # equation src
            _return = equation['RETURNS']
            # check if exist
            _body_integral = equation.get('BODY-INTEGRAL')
            _body_first_derivative = equation.get(
                'BODY-FIRST-DERIVATIVE'
            )
            _body_second_derivative = equation.get(
                'BODY-SECOND-DERIVATIVE'
            )
            # custom integral
            _custom_integral = equation.get('CUSTOM-INTEGRAL')

            # eq summary
            eq_summary = {
                'id': id,
                'body': _body,
                'args': _args,
                'parms': _parms,
                'return': _return,
                'body_integral': _body_integral,
                'body_first_derivative': _body_first_derivative,
                'body_second_derivative': _body_second_derivative,
                'custom_integral': _custom_integral
            }
            return eq_summary
        except Exception as e:
            raise Exception(f'Loading error {e}!')

    def eqs_structure(self, res_format: Literal['dict', 'json'] = 'dict'):
        '''
        Display all equations details

        Parameters
        ----------
        None

        Returns
        -------
        eq_summary : dict
            equation summary
        '''
        try:
            # equation list
            eq_num = self.eq_num

            # eq summary
            eq_summary = {}

            # looping through equations
            for id in range(eq_num):
                # equation id
                equation = self.equations[id]
                # equation body
                _body = equation['BODY']
                # equation args
                _args = equation['ARGS']
                # equation params
                _parms = equation['PARMS']
                # equation src
                _return = equation['RETURNS']
                # check if exist
                _body_integral = equation.get('BODY-INTEGRAL')
                _body_first_derivative = equation.get(
                    'BODY-FIRST-DERIVATIVE')
                _body_second_derivative = equation.get(
                    'BODY-SECOND-DERIVATIVE')
                # custom integral
                _custom_integral = equation.get('CUSTOM-INTEGRAL')

                # eq summary
                eq_summary[f"equation-{id+1}"] = {
                    'id': id,
                    'body': _body,
                    'args': _args,
                    'parms': _parms,
                    'return': _return,
                    'body_integral': _body_integral,
                    'body_first_derivative': _body_first_derivative,
                    'body_second_derivative': _body_second_derivative,
                    'custom_integral': _custom_integral
                }

            # check format
            if res_format == 'dict':
                return eq_summary
            elif res_format == 'json':
                return json.dumps(eq_summary, indent=4)

        except Exception as e:
            raise Exception(f'Loading error {e}!')

    @property
    def table_columns(
        self,
        column_name: str = 'COLUMNS',
    ) -> List[str]:
        '''
        Display table columns defined in `yml file`

        Parameters
        ----------
        column_name : str, optional
            column name (default is 'COLUMNS')

        Returns
        -------
        columns : list
            table columns

        '''
        try:
            # table structure
            table_structure = self.table_structure

            # check table structure
            if table_structure is None:
                logger.error('Table structure not defined!')
                raise

            # res
            columns = table_structure.get(column_name, None)
            # check columns
            if columns is None:
                logger.error(f'Column {column_name} not found!')
                raise

            # res
            return columns

        except Exception as e:
            logger.error(f'Loading error {e}!')
            return []

    @property
    def table_units(self, unit_name: str = 'UNIT'):
        '''
        Display table units defined in `yml file`

        Parameters
        ----------
        unit_name : str, optional
            unit name (default is 'UNIT')

        Returns
        -------
        units : list
            table units
        '''
        try:
            # table structure
            table_structure = self.table_structure

            # check table structure
            if table_structure is None:
                raise Exception('Table structure not defined!')

            # res
            units = table_structure.get(unit_name, None)
            # check units
            if units is None:
                raise Exception(f'Unit {unit_name} not found!')

            # res
            return units

        except Exception as e:
            logger.error(f'Loading error {e}!')
            return []

    @property
    def table_symbols(self, symbol_name: str = 'SYMBOL'):
        '''
        Display table symbols defined in `yml file`

        Parameters
        ----------
        symbol_name : str, optional
            symbol name (default is 'SYMBOL')

        Returns
        -------
        symbols : list
            table symbols
        '''
        try:
            # table structure
            table_structure = self.table_structure

            # check table structure
            if table_structure is None:
                raise Exception('Table structure not defined!')

            # res
            symbols = table_structure.get(symbol_name, None)
            # check symbols
            if symbols is None:
                raise Exception(f'Symbol {symbol_name} not found!')

            # res
            return symbols

        except Exception as e:
            logger.error(f'Loading error {e}!')
            return []

    def eq_info(self):
        '''Get equation information.'''
        try:
            # get return
            _return = self.returns

            # check length
            if len(_return) == 1:
                return list(_return.values())[0]
            else:
                raise Exception("Every equation has only one return")
        except Exception as e:
            raise Exception(f'Loading error {e}!')

    def cal(
        self,
        message: str = '',
        decimal_accuracy: int = 4,
        **args
    ) -> EquationResult:
        '''
        Execute a function

        Parameters
        ----------
        message : str
            message to be printed
        decimal_accuracy : int
            decimal accuracy (default is 4)
        args : dict
            a dictionary contains variable names and values as

        Returns
        -------
        eq_data : dict
            calculation result

        Examples
        --------
        >>> res = cal(message=f'{comp1} Vapor Pressure', T=120,P=1)
        >>> print(res)
        '''
        try:
            # equation info
            eq_info = self.eq_info()
            # databook and table name
            eq_src = {
                'databook_name': self.databook_name,
                'table_name': self.table_name,
            }
            # update
            eq_info.update(eq_src)

            # build parms dict
            _parms = self.load_parms_v2()
            # execute equation
            # res
            res = None

            # NOTE: execute equation
            # check body
            if self.body is None or self.body == 'None':
                raise Exception('Equation body not defined!')

            res = self.eqExe(self.body, _parms, args=args)

            if res is not None:
                res = round(res, decimal_accuracy)
            else:
                res = 'Error'

            # format data
            eq_data = format_eq_data(res, eq_info, message or 'No message')

            # res
            return eq_data
        except Exception as e:
            logger.error(f'Calculation error {e}!')
            raise Exception(f'Calculation error {e}!')

    def cal_integral(self, **args):
        '''
        Calculate integral

        Parameters
        ----------
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> # heat capacity integral
        >>> res = cal_integral(T1=120,T2=150)
        >>> print(res)
        '''
        try:
            # build parms dict
            _parms = self.load_parms_v2()
            # execute equation
            res = self.eqExe(
                body=self.body_integral,
                parms=_parms,
                args=args
            )

            return res
        except Exception as e:
            raise Exception('Loading integral calculation failed!, ', e)

    def cal_custom_integral(self, equation_name: str, **args):
        '''
        Calculate custom integral

        Parameters
        ----------
        equation_name : str
            equation name
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> res = cal_custom_integral('Cp/RT',T1=120,T2=150)
        >>> print(res)
        '''
        try:
            # check
            if equation_name is None:
                raise Exception('Equation name not defined!')

            # check equation name exists
            if equation_name not in self._custom_integral:
                raise Exception('Equation name not found!')

            # build parms dict
            _parms = self.load_parms_v2()

            # check
            if len(self._custom_integral) > 0:
                # body
                _body_lines = self._custom_integral[equation_name]
                # stringify
                _body = ";".join(_body_lines)
            else:
                _body = None
            # execute equation
            res = self.eqExe(_body, _parms, args=args)
            return res
        except Exception as e:
            raise Exception('Loading custom integral failed!, ', e)

    def cal_first_derivative(self, **args):
        '''
        Calculate first derivative

        Parameters
        ----------
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> res = cal_first_derivative(T=120,P=1)
        >>> print(res)
        '''
        try:
            # check
            if (
                self.body_first_derivative is None or
                self.body_first_derivative == 'None'
            ):
                print('The first derivative not defined!')

            # build parms dict
            _parms = self.load_parms_v2()

            # execute equation
            res = self.eqExe(
                body=self.body_first_derivative,
                parms=_parms,
                args=args
            )

            # res
            return res
        except Exception as e:
            logger.error(f'Derivation calculation failed!, {e}')
            return None

    def cal_second_derivative(self, **args):
        '''
        Calculate second derivative

        Parameters
        ----------
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> res = cal_second_derivative(T=120,P=1)
        >>> print(res)
        '''
        try:
            # check
            if (self.body_second_derivative is None or
                    self.body_second_derivative == 'None'):
                print('The second derivative not defined!')

            # build parms dict
            _parms = self.load_parms_v2()
            # execute equation
            res = self.eqExe(self.body_second_derivative, _parms, args=args)
            return res
        except Exception as e:
            raise Exception('Derivation calculation failed!, ', e)

    def load_parms(self):
        '''
        Load parms values and store in a dict,
        These parameters are constant values defined in an equation.
        '''
        try:
            # trans data (taken from csv)
            trans_data = self.trans_data
            # looping through self.parms
            # check parms
            if isinstance(self.parms, dict):
                # NOTE: loaded parms (taken from reference)
                _parms_name = list(self.parms.keys())
                # from symbol
                _parms_name = [
                    value['symbol']
                    for key, value in self.parms.items()
                ]

                # NOTE: create params dict
                _parms = {
                    value['symbol']:
                    float(value['value'] or 0)/float(value['unit'] or 1)
                    for key, value in trans_data.items() if value['symbol'] in _parms_name
                }
            else:
                _parms = {}
            return _parms
        except Exception as e:
            raise Exception("Loading equation parameters failed!, ", e)

    def load_parms_v2(self):
        """
        Load parameter values and store in a dict.
        These parameters are constant values defined in an equation.
        """
        try:
            trans_data = self.trans_data

            if isinstance(self.parms, dict):
                # Get the list of symbols we need
                parm_symbols = [v["symbol"] for v in self.parms.values()]

                def safe_float(x, default=1.0):
                    """Return float(x) if numeric, else default."""
                    try:
                        return float(x)
                    except (ValueError, TypeError):
                        return default

                # Build params dict
                parms = {
                    v["symbol"]: float(v.get("value", 0)) /
                    safe_float(v.get("unit"), 1.0)
                    for v in trans_data.values()
                    if v["symbol"] in parm_symbols
                }
            else:
                parms = {}

            return parms

        except Exception as e:
            raise Exception("Loading equation parameters failed!") from e

    def equation_body(self):
        '''
        Display equation body

        Parameters
        ----------
        None

        Returns
        -------
        body : str
            equation body
        '''
        return self.body

    def equation_parms(self, dataframe=True):
        '''
        Display equation parms

        Parameters
        ----------
        value : bool, optional
            DESCRIPTION. The default is True.

        Returns
        -------
        df : dataframe
            equation parms
        '''
        df = pd.DataFrame(self.parms)

        if dataframe:
            return df
        else:
            return self.parms

    def equation_args(self, dataframe=True):
        '''
        Display equation args,

        Parameters
        ----------
        value : bool, optional
            DESCRIPTION. The default is True.

        Returns
        -------
        df : dataframe
            equation args
        '''
        df = pd.DataFrame(self.args)

        if dataframe:
            return df
        else:
            return self.args

    def equation_return(self, dataframe=True):
        '''
        Display equation return,

        Parameters
        ----------
        value : bool, optional
            DESCRIPTION. The default is True.


        Returns
        -------
        df : dataframe
            equation return
        '''
        df = pd.DataFrame(self.returns)

        if dataframe:
            return df
        else:
            return self.returns

    def eqSet(self):
        '''
        Set the equation used for calculation

        Parameters
        ----------
        transform_api_data : dict
            transform api data

        Returns
        -------
        None.
        '''
        # set
        transform_api_data = self.trans_data

        # eq
        Eq_data = 0
        Eq_data = int(transform_api_data['Eq']['value'])
        # save eq id
        self.eq_id = Eq_data

        # load equation
        eq_summary = self.eq_structure(Eq_data)

        # REVIEW: extract data
        _body = eq_summary['body']
        self.body = ';'.join(_body)
        # check
        if eq_summary['parms'] is not None:
            self.parms = eq_summary['parms']
            # REVIEW
            # params value
            # self.__parms_values = self.load_parms()
        else:
            self.parms = []
        # check
        if eq_summary['args'] is not None:
            self.args = eq_summary['args']
            # make arg symbols
            self.arg_symbols = self.make_arg_symbols(self.args)
        else:
            self.args = []
        # check
        if eq_summary['return'] is not None:
            self.returns = eq_summary['return']
            # make return symbols
            self.return_symbols = self.make_return_symbols(self.returns)
        else:
            self.returns = []
        # integral
        body_integral = eq_summary['body_integral']
        # check
        if body_integral is not None and body_integral != 'None':
            self.body_integral = ";".join(body_integral)
        else:
            self.body_integral = None
        # first derivative
        first_derivative = eq_summary['body_first_derivative']
        # check
        if first_derivative is not None and first_derivative != 'None':
            self.body_first_derivative = ";".join(first_derivative)
        else:
            self.body_first_derivative = None
        # second derivative
        second_derivative = eq_summary['body_second_derivative']
        # check
        if second_derivative is not None and second_derivative != 'None':
            self.body_second_derivative = ";".join(second_derivative)
        else:
            self.body_second_derivative = None
        # custom integral
        custom_integral = eq_summary['custom_integral']
        # check
        if custom_integral is not None and custom_integral != 'None':
            self._custom_integral = custom_integral
        else:
            self._custom_integral = {}

        # update __prop_equation
        self.__prop_equation = {
            'BODY': self.body,
            'PARMS': self.parms,
            'ARGS': self.args,
            'RETURNS': self.returns,
            'BODY-INTEGRAL': self.body_integral,
            'BODY-FIRST-DERIVATIVE': self.body_first_derivative,
            'BODY-SECOND-DERIVATIVE': self.body_second_derivative,
            'CUSTOM-INTEGRAL': self._custom_integral
        }

        # check params
        if len(self.parms) > 0:
            self.__parms_values = self.load_parms_v2()

    def eqExe(self, body, parms, args):
        '''
        Execute the function having args, parameters and body

        Parameters
        ----------
        body : str
            function body
        parms : dict
            parameters
        args : dict
            args

        Returns
        -------
        res : float
            calculation result
        '''
        # check body
        if body is None:
            print('Function body not defined!')
            return None

        # Define a namespace dictionary for eval
        namespace = {'args': args, "parms": parms}
        # Import math module within the function
        namespace['math'] = math
        # Execute the body within the namespace
        exec(body, namespace)
        # Return the result
        return namespace['res']

    def to_dict(self):
        '''
        Convert equation to dict

        Parameters
        ----------
        None.

        Returns
        -------
        res : str
            equation in dict
        '''
        # create dict
        res = self.__prop_equation
        # yml
        # _eq_yml = _eq
        # convert to yml
        # res = yaml.dump(_eq_yml)

        return res

    def check_custom_integral_equation_body(self, equation_name) -> str:
        '''
        Displays the equation body of custom integral by equation name

        Parameters
        ----------
        equation_name : str
            equation name

        Returns
        -------
        body : str
            equation body

        Examples
        --------
        >>> body = custom_integral_equation_body('Cp/RT')
        '''
        try:
            # check
            if self._custom_integral is None:
                raise Exception('Custom integral not defined!')

            if equation_name is None:
                raise Exception('Equation name not defined!')

            if equation_name not in self._custom_integral:
                raise Exception('Equation name not found!')
            # get equation body
            body = self._custom_integral.get(equation_name, 'None')
            return body
        except Exception as e:
            raise Exception("Loading custom integral body failed!, ", e)

    def make_arg_symbols(self, args) -> dict:
        '''
        Make argument symbols

        Parameters
        ----------
        args : dict
            arguments

        Returns
        -------
        None.
        '''
        try:
            # reset
            arg_symbols = {}

            # check
            if args is not None:
                if isinstance(args, dict):
                    for key, value in args.items():
                        # symbol
                        _symbol = args[key].get('symbol')
                        # set
                        arg_symbols[_symbol] = {
                            'name': args[key].get('name'),
                            'symbol': _symbol,
                            'unit': args[key].get('unit'),
                        }

                    # return
                    return arg_symbols

            return {}
        except Exception as e:
            raise Exception("Making argument symbols failed!, ", e)

    def make_return_symbols(self, returns) -> dict:
        '''
        Make return symbols

        Parameters
        ----------
        returns : dict
            returns

        Returns
        -------
        None.
        '''
        try:
            # reset
            return_symbols = {}

            # check
            if returns is not None:
                if isinstance(returns, dict):
                    for key, value in returns.items():
                        # symbol
                        _symbol = returns[key].get('symbol')
                        # set
                        return_symbols[_symbol] = {
                            'name': returns[key].get('name'),
                            'symbol': _symbol,
                            'unit': returns[key].get('unit'),
                        }

                # return
                return return_symbols

            return {}
        except Exception as e:
            raise Exception("Making return symbols failed!, ", e)

table_columns: List[str] property

Display table columns defined in yml file

Parameters

column_name : str, optional column name (default is 'COLUMNS')

Returns

columns : list table columns

table_structure property

Get table structure from yml file (if exists)

table_symbols property

Display table symbols defined in yml file

Parameters

symbol_name : str, optional symbol name (default is 'SYMBOL')

Returns

symbols : list table symbols

table_units property

Display table units defined in yml file

Parameters

unit_name : str, optional unit name (default is 'UNIT')

Returns

units : list table units

table_values property

Get table values from yml file (if exists)

__init__(databook_name, table_name, equations, table_values=None, table_structure=None)

Initialize the TableEquation class.

Parameters

databook_name : str Name of the databook. table_name : str Name of the table. equations : list List of equations. table_values : list, optional Values for the table (default is None), if provided in yml file. table_structure : dict, optional Structure of the table (default is None), if provided in yml file.

Source code in pyThermoDB/core/tableequation.py

def __init__(
    self,
    databook_name,
    table_name,
    equations,
    table_values: Optional[List | Dict] = None,
    table_structure: Optional[Dict[str, Any]] = None
):
    '''
    Initialize the TableEquation class.

    Parameters
    ----------
    databook_name : str
        Name of the databook.
    table_name : str
        Name of the table.
    equations : list
        List of equations.
    table_values : list, optional
        Values for the table (default is None), if provided in yml file.
    table_structure : dict, optional
        Structure of the table (default is None), if provided in yml file.
    '''
    self.databook_name = databook_name
    self.table_name = table_name
    self.equations = equations  # equation list structures (yml file)
    # number of equations
    self.eq_num = len(equations)
    # table values (yml)
    self.__table_values = table_values if table_values else None
    # table structure (yml)
    self.__table_structure = table_structure if table_structure else None

cal(message='', decimal_accuracy=4, **args)

Execute a function

Parameters

message : str message to be printed decimal_accuracy : int decimal accuracy (default is 4) args : dict a dictionary contains variable names and values as

Returns

eq_data : dict calculation result

Examples

res = cal(message=f'{comp1} Vapor Pressure', T=120,P=1) print(res)

Source code in pyThermoDB/core/tableequation.py

def cal(
    self,
    message: str = '',
    decimal_accuracy: int = 4,
    **args
) -> EquationResult:
    '''
    Execute a function

    Parameters
    ----------
    message : str
        message to be printed
    decimal_accuracy : int
        decimal accuracy (default is 4)
    args : dict
        a dictionary contains variable names and values as

    Returns
    -------
    eq_data : dict
        calculation result

    Examples
    --------
    >>> res = cal(message=f'{comp1} Vapor Pressure', T=120,P=1)
    >>> print(res)
    '''
    try:
        # equation info
        eq_info = self.eq_info()
        # databook and table name
        eq_src = {
            'databook_name': self.databook_name,
            'table_name': self.table_name,
        }
        # update
        eq_info.update(eq_src)

        # build parms dict
        _parms = self.load_parms_v2()
        # execute equation
        # res
        res = None

        # NOTE: execute equation
        # check body
        if self.body is None or self.body == 'None':
            raise Exception('Equation body not defined!')

        res = self.eqExe(self.body, _parms, args=args)

        if res is not None:
            res = round(res, decimal_accuracy)
        else:
            res = 'Error'

        # format data
        eq_data = format_eq_data(res, eq_info, message or 'No message')

        # res
        return eq_data
    except Exception as e:
        logger.error(f'Calculation error {e}!')
        raise Exception(f'Calculation error {e}!')

cal_custom_integral(equation_name, **args)

Calculate custom integral

Parameters

equation_name : str equation name args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

res = cal_custom_integral('Cp/RT',T1=120,T2=150) print(res)

Source code in pyThermoDB/core/tableequation.py

def cal_custom_integral(self, equation_name: str, **args):
    '''
    Calculate custom integral

    Parameters
    ----------
    equation_name : str
        equation name
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> res = cal_custom_integral('Cp/RT',T1=120,T2=150)
    >>> print(res)
    '''
    try:
        # check
        if equation_name is None:
            raise Exception('Equation name not defined!')

        # check equation name exists
        if equation_name not in self._custom_integral:
            raise Exception('Equation name not found!')

        # build parms dict
        _parms = self.load_parms_v2()

        # check
        if len(self._custom_integral) > 0:
            # body
            _body_lines = self._custom_integral[equation_name]
            # stringify
            _body = ";".join(_body_lines)
        else:
            _body = None
        # execute equation
        res = self.eqExe(_body, _parms, args=args)
        return res
    except Exception as e:
        raise Exception('Loading custom integral failed!, ', e)

cal_first_derivative(**args)

Calculate first derivative

Parameters

args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

res = cal_first_derivative(T=120,P=1) print(res)

Source code in pyThermoDB/core/tableequation.py

def cal_first_derivative(self, **args):
    '''
    Calculate first derivative

    Parameters
    ----------
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> res = cal_first_derivative(T=120,P=1)
    >>> print(res)
    '''
    try:
        # check
        if (
            self.body_first_derivative is None or
            self.body_first_derivative == 'None'
        ):
            print('The first derivative not defined!')

        # build parms dict
        _parms = self.load_parms_v2()

        # execute equation
        res = self.eqExe(
            body=self.body_first_derivative,
            parms=_parms,
            args=args
        )

        # res
        return res
    except Exception as e:
        logger.error(f'Derivation calculation failed!, {e}')
        return None

cal_integral(**args)

Calculate integral

Parameters

args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

heat capacity integral

res = cal_integral(T1=120,T2=150) print(res)

Source code in pyThermoDB/core/tableequation.py

def cal_integral(self, **args):
    '''
    Calculate integral

    Parameters
    ----------
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> # heat capacity integral
    >>> res = cal_integral(T1=120,T2=150)
    >>> print(res)
    '''
    try:
        # build parms dict
        _parms = self.load_parms_v2()
        # execute equation
        res = self.eqExe(
            body=self.body_integral,
            parms=_parms,
            args=args
        )

        return res
    except Exception as e:
        raise Exception('Loading integral calculation failed!, ', e)

cal_second_derivative(**args)

Calculate second derivative

Parameters

args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

res = cal_second_derivative(T=120,P=1) print(res)

Source code in pyThermoDB/core/tableequation.py

def cal_second_derivative(self, **args):
    '''
    Calculate second derivative

    Parameters
    ----------
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> res = cal_second_derivative(T=120,P=1)
    >>> print(res)
    '''
    try:
        # check
        if (self.body_second_derivative is None or
                self.body_second_derivative == 'None'):
            print('The second derivative not defined!')

        # build parms dict
        _parms = self.load_parms_v2()
        # execute equation
        res = self.eqExe(self.body_second_derivative, _parms, args=args)
        return res
    except Exception as e:
        raise Exception('Derivation calculation failed!, ', e)

check_custom_integral_equation_body(equation_name)

Displays the equation body of custom integral by equation name

Parameters

equation_name : str equation name

Returns

body : str equation body

Examples

body = custom_integral_equation_body('Cp/RT')

Source code in pyThermoDB/core/tableequation.py

def check_custom_integral_equation_body(self, equation_name) -> str:
    '''
    Displays the equation body of custom integral by equation name

    Parameters
    ----------
    equation_name : str
        equation name

    Returns
    -------
    body : str
        equation body

    Examples
    --------
    >>> body = custom_integral_equation_body('Cp/RT')
    '''
    try:
        # check
        if self._custom_integral is None:
            raise Exception('Custom integral not defined!')

        if equation_name is None:
            raise Exception('Equation name not defined!')

        if equation_name not in self._custom_integral:
            raise Exception('Equation name not found!')
        # get equation body
        body = self._custom_integral.get(equation_name, 'None')
        return body
    except Exception as e:
        raise Exception("Loading custom integral body failed!, ", e)

eqExe(body, parms, args)

Execute the function having args, parameters and body

Parameters

body : str function body parms : dict parameters args : dict args

Returns

res : float calculation result

Source code in pyThermoDB/core/tableequation.py

def eqExe(self, body, parms, args):
    '''
    Execute the function having args, parameters and body

    Parameters
    ----------
    body : str
        function body
    parms : dict
        parameters
    args : dict
        args

    Returns
    -------
    res : float
        calculation result
    '''
    # check body
    if body is None:
        print('Function body not defined!')
        return None

    # Define a namespace dictionary for eval
    namespace = {'args': args, "parms": parms}
    # Import math module within the function
    namespace['math'] = math
    # Execute the body within the namespace
    exec(body, namespace)
    # Return the result
    return namespace['res']

eqSet()

Set the equation used for calculation

Parameters

transform_api_data : dict transform api data

Returns

None.

Source code in pyThermoDB/core/tableequation.py

def eqSet(self):
    '''
    Set the equation used for calculation

    Parameters
    ----------
    transform_api_data : dict
        transform api data

    Returns
    -------
    None.
    '''
    # set
    transform_api_data = self.trans_data

    # eq
    Eq_data = 0
    Eq_data = int(transform_api_data['Eq']['value'])
    # save eq id
    self.eq_id = Eq_data

    # load equation
    eq_summary = self.eq_structure(Eq_data)

    # REVIEW: extract data
    _body = eq_summary['body']
    self.body = ';'.join(_body)
    # check
    if eq_summary['parms'] is not None:
        self.parms = eq_summary['parms']
        # REVIEW
        # params value
        # self.__parms_values = self.load_parms()
    else:
        self.parms = []
    # check
    if eq_summary['args'] is not None:
        self.args = eq_summary['args']
        # make arg symbols
        self.arg_symbols = self.make_arg_symbols(self.args)
    else:
        self.args = []
    # check
    if eq_summary['return'] is not None:
        self.returns = eq_summary['return']
        # make return symbols
        self.return_symbols = self.make_return_symbols(self.returns)
    else:
        self.returns = []
    # integral
    body_integral = eq_summary['body_integral']
    # check
    if body_integral is not None and body_integral != 'None':
        self.body_integral = ";".join(body_integral)
    else:
        self.body_integral = None
    # first derivative
    first_derivative = eq_summary['body_first_derivative']
    # check
    if first_derivative is not None and first_derivative != 'None':
        self.body_first_derivative = ";".join(first_derivative)
    else:
        self.body_first_derivative = None
    # second derivative
    second_derivative = eq_summary['body_second_derivative']
    # check
    if second_derivative is not None and second_derivative != 'None':
        self.body_second_derivative = ";".join(second_derivative)
    else:
        self.body_second_derivative = None
    # custom integral
    custom_integral = eq_summary['custom_integral']
    # check
    if custom_integral is not None and custom_integral != 'None':
        self._custom_integral = custom_integral
    else:
        self._custom_integral = {}

    # update __prop_equation
    self.__prop_equation = {
        'BODY': self.body,
        'PARMS': self.parms,
        'ARGS': self.args,
        'RETURNS': self.returns,
        'BODY-INTEGRAL': self.body_integral,
        'BODY-FIRST-DERIVATIVE': self.body_first_derivative,
        'BODY-SECOND-DERIVATIVE': self.body_second_derivative,
        'CUSTOM-INTEGRAL': self._custom_integral
    }

    # check params
    if len(self.parms) > 0:
        self.__parms_values = self.load_parms_v2()

eq_info()

Get equation information.

Source code in pyThermoDB/core/tableequation.py

def eq_info(self):
    '''Get equation information.'''
    try:
        # get return
        _return = self.returns

        # check length
        if len(_return) == 1:
            return list(_return.values())[0]
        else:
            raise Exception("Every equation has only one return")
    except Exception as e:
        raise Exception(f'Loading error {e}!')

eq_structure(id=1)

Display equation details

Parameters

id : int equation id (from 1 to ...), default is 1

Returns

eq_summary : dict equation summary

Source code in pyThermoDB/core/tableequation.py

def eq_structure(self, id=1):
    '''
    Display equation details

    Parameters
    ----------
    id : int
        equation id (from 1 to ...), default is 1

    Returns
    -------
    eq_summary : dict
        equation summary
    '''
    try:
        # set id
        id = int(id)-1
        # equation id
        equation = self.equations[id]
        # equation body
        _body = equation['BODY']
        # equation args
        _args = equation['ARGS']
        # equation params
        _parms = equation['PARMS']
        # equation src
        _return = equation['RETURNS']
        # check if exist
        _body_integral = equation.get('BODY-INTEGRAL')
        _body_first_derivative = equation.get(
            'BODY-FIRST-DERIVATIVE'
        )
        _body_second_derivative = equation.get(
            'BODY-SECOND-DERIVATIVE'
        )
        # custom integral
        _custom_integral = equation.get('CUSTOM-INTEGRAL')

        # eq summary
        eq_summary = {
            'id': id,
            'body': _body,
            'args': _args,
            'parms': _parms,
            'return': _return,
            'body_integral': _body_integral,
            'body_first_derivative': _body_first_derivative,
            'body_second_derivative': _body_second_derivative,
            'custom_integral': _custom_integral
        }
        return eq_summary
    except Exception as e:
        raise Exception(f'Loading error {e}!')

eqs_structure(res_format='dict')

Display all equations details

Parameters

None

Returns

eq_summary : dict equation summary

Source code in pyThermoDB/core/tableequation.py

def eqs_structure(self, res_format: Literal['dict', 'json'] = 'dict'):
    '''
    Display all equations details

    Parameters
    ----------
    None

    Returns
    -------
    eq_summary : dict
        equation summary
    '''
    try:
        # equation list
        eq_num = self.eq_num

        # eq summary
        eq_summary = {}

        # looping through equations
        for id in range(eq_num):
            # equation id
            equation = self.equations[id]
            # equation body
            _body = equation['BODY']
            # equation args
            _args = equation['ARGS']
            # equation params
            _parms = equation['PARMS']
            # equation src
            _return = equation['RETURNS']
            # check if exist
            _body_integral = equation.get('BODY-INTEGRAL')
            _body_first_derivative = equation.get(
                'BODY-FIRST-DERIVATIVE')
            _body_second_derivative = equation.get(
                'BODY-SECOND-DERIVATIVE')
            # custom integral
            _custom_integral = equation.get('CUSTOM-INTEGRAL')

            # eq summary
            eq_summary[f"equation-{id+1}"] = {
                'id': id,
                'body': _body,
                'args': _args,
                'parms': _parms,
                'return': _return,
                'body_integral': _body_integral,
                'body_first_derivative': _body_first_derivative,
                'body_second_derivative': _body_second_derivative,
                'custom_integral': _custom_integral
            }

        # check format
        if res_format == 'dict':
            return eq_summary
        elif res_format == 'json':
            return json.dumps(eq_summary, indent=4)

    except Exception as e:
        raise Exception(f'Loading error {e}!')

equation_args(dataframe=True)

Display equation args,

Parameters

value : bool, optional DESCRIPTION. The default is True.

Returns

df : dataframe equation args

Source code in pyThermoDB/core/tableequation.py

def equation_args(self, dataframe=True):
    '''
    Display equation args,

    Parameters
    ----------
    value : bool, optional
        DESCRIPTION. The default is True.

    Returns
    -------
    df : dataframe
        equation args
    '''
    df = pd.DataFrame(self.args)

    if dataframe:
        return df
    else:
        return self.args

equation_body()

Display equation body

Parameters

None

Returns

body : str equation body

Source code in pyThermoDB/core/tableequation.py

def equation_body(self):
    '''
    Display equation body

    Parameters
    ----------
    None

    Returns
    -------
    body : str
        equation body
    '''
    return self.body

equation_parms(dataframe=True)

Display equation parms

Parameters

value : bool, optional DESCRIPTION. The default is True.

Returns

df : dataframe equation parms

Source code in pyThermoDB/core/tableequation.py

def equation_parms(self, dataframe=True):
    '''
    Display equation parms

    Parameters
    ----------
    value : bool, optional
        DESCRIPTION. The default is True.

    Returns
    -------
    df : dataframe
        equation parms
    '''
    df = pd.DataFrame(self.parms)

    if dataframe:
        return df
    else:
        return self.parms

equation_return(dataframe=True)

Display equation return,

Parameters

value : bool, optional DESCRIPTION. The default is True.

Returns

df : dataframe equation return

Source code in pyThermoDB/core/tableequation.py

def equation_return(self, dataframe=True):
    '''
    Display equation return,

    Parameters
    ----------
    value : bool, optional
        DESCRIPTION. The default is True.


    Returns
    -------
    df : dataframe
        equation return
    '''
    df = pd.DataFrame(self.returns)

    if dataframe:
        return df
    else:
        return self.returns

load_parms()

Load parms values and store in a dict, These parameters are constant values defined in an equation.

Source code in pyThermoDB/core/tableequation.py

def load_parms(self):
    '''
    Load parms values and store in a dict,
    These parameters are constant values defined in an equation.
    '''
    try:
        # trans data (taken from csv)
        trans_data = self.trans_data
        # looping through self.parms
        # check parms
        if isinstance(self.parms, dict):
            # NOTE: loaded parms (taken from reference)
            _parms_name = list(self.parms.keys())
            # from symbol
            _parms_name = [
                value['symbol']
                for key, value in self.parms.items()
            ]

            # NOTE: create params dict
            _parms = {
                value['symbol']:
                float(value['value'] or 0)/float(value['unit'] or 1)
                for key, value in trans_data.items() if value['symbol'] in _parms_name
            }
        else:
            _parms = {}
        return _parms
    except Exception as e:
        raise Exception("Loading equation parameters failed!, ", e)

load_parms_v2()

Load parameter values and store in a dict. These parameters are constant values defined in an equation.

Source code in pyThermoDB/core/tableequation.py

def load_parms_v2(self):
    """
    Load parameter values and store in a dict.
    These parameters are constant values defined in an equation.
    """
    try:
        trans_data = self.trans_data

        if isinstance(self.parms, dict):
            # Get the list of symbols we need
            parm_symbols = [v["symbol"] for v in self.parms.values()]

            def safe_float(x, default=1.0):
                """Return float(x) if numeric, else default."""
                try:
                    return float(x)
                except (ValueError, TypeError):
                    return default

            # Build params dict
            parms = {
                v["symbol"]: float(v.get("value", 0)) /
                safe_float(v.get("unit"), 1.0)
                for v in trans_data.values()
                if v["symbol"] in parm_symbols
            }
        else:
            parms = {}

        return parms

    except Exception as e:
        raise Exception("Loading equation parameters failed!") from e

make_arg_symbols(args)

Make argument symbols

Parameters

args : dict arguments

Returns

None.

Source code in pyThermoDB/core/tableequation.py

def make_arg_symbols(self, args) -> dict:
    '''
    Make argument symbols

    Parameters
    ----------
    args : dict
        arguments

    Returns
    -------
    None.
    '''
    try:
        # reset
        arg_symbols = {}

        # check
        if args is not None:
            if isinstance(args, dict):
                for key, value in args.items():
                    # symbol
                    _symbol = args[key].get('symbol')
                    # set
                    arg_symbols[_symbol] = {
                        'name': args[key].get('name'),
                        'symbol': _symbol,
                        'unit': args[key].get('unit'),
                    }

                # return
                return arg_symbols

        return {}
    except Exception as e:
        raise Exception("Making argument symbols failed!, ", e)

make_return_symbols(returns)

Make return symbols

Parameters

returns : dict returns

Returns

None.

Source code in pyThermoDB/core/tableequation.py

def make_return_symbols(self, returns) -> dict:
    '''
    Make return symbols

    Parameters
    ----------
    returns : dict
        returns

    Returns
    -------
    None.
    '''
    try:
        # reset
        return_symbols = {}

        # check
        if returns is not None:
            if isinstance(returns, dict):
                for key, value in returns.items():
                    # symbol
                    _symbol = returns[key].get('symbol')
                    # set
                    return_symbols[_symbol] = {
                        'name': returns[key].get('name'),
                        'symbol': _symbol,
                        'unit': returns[key].get('unit'),
                    }

            # return
            return return_symbols

        return {}
    except Exception as e:
        raise Exception("Making return symbols failed!, ", e)

to_dict()

Convert equation to dict

Parameters

None.

Returns

res : str equation in dict

Source code in pyThermoDB/core/tableequation.py

def to_dict(self):
    '''
    Convert equation to dict

    Parameters
    ----------
    None.

    Returns
    -------
    res : str
        equation in dict
    '''
    # create dict
    res = self.__prop_equation
    # yml
    # _eq_yml = _eq
    # convert to yml
    # res = yaml.dump(_eq_yml)

    return res

tabledata

TableData

Source code in pyThermoDB/core/tabledata.py

class TableData:
    # vars
    __trans_data = {}
    __prop_data = {}

    def __init__(
        self,
        databook_name,
        table_name,
        table_data,
        table_values: Optional[List | Dict] = None,
        table_structure: Optional[Dict[str, Any]] = None
    ):
        '''
        Initialize TableData class

        Parameters
        ----------
        databook_name : str
            databook name
        table_name : str
            table name
        table_data : dict
            table data (dict), taken directly from yml file
        table_values : list | dict, optional
            table values (default: None), taken directly from yml file if exists
        table_structure : dict, optional
            table structure (default: None), taken directly from yml file if exists
        '''
        self.databook_name = databook_name
        self.table_name = table_name
        self.table_data = table_data  # reference template (yml)
        # table values (yml)
        self.__table_values = table_values if table_values else None
        self.__table_structure = table_structure if table_structure else None

    @property
    def trans_data(self):
        return self.__trans_data

    @trans_data.setter
    def trans_data(self, value):
        self.__trans_data = {}
        self.__trans_data = value

    @property
    def prop_data(self):
        return self.__prop_data

    @prop_data.setter
    def prop_data(self, value):
        self.__prop_data = {}
        exclude_key = 'data'
        self.__prop_data = {key: value for key,
                            value in value.items() if key != exclude_key}

    @property
    def table_values(self):
        '''Get table values from yml file (if exists)'''
        if self.__table_values:
            return self.__table_values
        else:
            msg = f"""No table values found in the following reference \n
            ::: {self.databook_name}
            :::  {self.table_name}!
            """
            print(msg)
            return None

    @property
    def table_structure(self):
        '''Get table structure from yml file (if exists)'''
        if self.__table_structure:
            return self.__table_structure
        else:
            msg = f"""No table structure found in the following reference \n
            ::: {self.databook_name}
            :::  {self.table_name}!
            """
            print(msg)
            return None

    @property
    def table_columns(self, column_name: str = 'COLUMNS') -> List[str]:
        '''
        Get table columns from data-table structure

        Parameters
        ----------
        column_name : str
            column name (default: 'COLUMNS')

        Returns
        -------
        columns : list
            list of columns
        '''
        try:
            return self.table_data[column_name]
        except KeyError:
            raise KeyError(
                "Table columns not found in the data table structure!")
        except Exception as e:
            raise Exception(f"Error retrieving table columns: {e}")

    @property
    def table_symbols(self, symbol_name: str = 'SYMBOL') -> List[str]:
        '''
        Get table symbols from data-table structure

        Parameters
        ----------
        symbol_name : str
            symbol name (default: 'SYMBOL')

        Returns
        -------
        symbols : list
            list of symbols
        '''
        try:
            return self.table_data[symbol_name]
        except KeyError:
            raise KeyError(
                "Table symbols not found in the data table structure!")
        except Exception as e:
            raise Exception(f"Error retrieving table symbols: {e}")

    @property
    def table_units(self, unit_name: str = 'UNIT') -> List[str]:
        '''
        Get table units from data-table structure

        Parameters
        ----------
        unit_name : str
            unit name (default: 'UNIT')

        Returns
        -------
        units : list
            list of units
        '''
        try:
            return self.table_data[unit_name]
        except KeyError:
            raise KeyError(
                "Table units not found in the data table structure!")
        except Exception as e:
            raise Exception(f"Error retrieving table units: {e}")

    def data_structure(self):
        '''
        Display data-table structure including `column names`, `symbol`, `units` and `values`
        '''
        # dataframe
        df = pd.DataFrame(self.table_data)
        # add ID column
        df.insert(0, 'ID', range(1, len(df) + 1))
        # arrange columns
        # change the position of ID column to the last
        cols = df.columns.tolist()
        cols.insert(len(cols), cols.pop(cols.index('ID')))
        df = df[cols]

        return df

    def get_property(self, property: str | int, message: Optional[str] = None) -> DataResult:
        '''
        Get a component property from data table structure

        Parameters
        ----------
        property : str | int
            property name or id
        message : str
            message to display when property is found or not found

        Returns
        -------
        data_dict : DataResult
            property result dict
        '''
        # ! get data for a selected component
        # dataframe
        df = pd.DataFrame(self.prop_data)

        get_data = None
        # choose a column
        if isinstance(property, str):
            # df = df[property_name]
            # look up prop_data dict
            prop_data_keys_ = [key.lower() for key in self.prop_data.keys()]

            # NOTE: property lower
            property_ = property.lower()

            # check key exists
            if property_ in prop_data_keys_:
                # loop through prop_data dict
                for key, value in self.prop_data.items():
                    # check key
                    if property_ == key.lower():
                        # value found
                        get_data = self.prop_data[key]
                        # property name
                        property = key
                        break
                # get_data = self.prop_data[property]
            else:
                # NOTE: symbol
                # check symbol value in each item
                for key, value in self.prop_data.items():
                    # check if property is in the symbol
                    if property == value['symbol']:
                        # value found
                        get_data = self.prop_data[key]
                        # property name
                        property = key
                        break

            # ! check if property found
            if get_data is None:
                raise ValueError(f"Property '{property}' not found!")
            # series
            sr = pd.Series(get_data, dtype='str')
            # print(type(sr))

        elif isinstance(property, int):
            # get column index
            column_index = df.columns[property-1]
            sr = df.loc[:, column_index]
            # print(type(sr))

        else:
            raise ValueError(f"loading error! {property} is not a valid type!")

        # convert to dict
        data_dict = DataResult(**sr.to_dict())
        # print(data_dict, type(data_dict))

        # property name
        if isinstance(property, str):
            data_dict['property_name'] = property
        else:
            data_dict['property_name'] = df.columns[property-1]

        # update message
        if message:
            data_dict['message'] = str(message)
        else:
            data_dict['message'] = 'No message'

        # add databook and table name
        data_dict['databook_name'] = self.databook_name if self.databook_name else 'No databook name'
        data_dict['table_name'] = self.table_name if self.table_name else 'No table name'

        # res
        return data_dict

    def insert(self, property: str | int, message: Optional[str] = None) -> DataResult:
        '''
        Get a component property from data table structure

        Parameters
        ----------
        property : str | int
            property name, symbol or id
        message : str
            message to display when property is found or not found

        Returns
        -------
        data_dict : DataResult
            property result dict
        '''
        # ! get data for a selected component
        # dataframe
        df = pd.DataFrame(self.prop_data)

        get_data = None
        # choose a column
        if isinstance(property, str):
            # df = df[property_name]
            # look up prop_data dict
            # check key exists
            if property in self.prop_data.keys():
                get_data = self.prop_data[property]
            else:
                # check symbol value in each item
                for key, value in self.prop_data.items():
                    if property == value['symbol']:
                        # value found
                        get_data = self.prop_data[key]
                        # property name
                        property = key
                        break
            if get_data is None:
                raise ValueError(f"Property '{property}' not found!")
            # series
            sr = pd.Series(get_data, dtype='str')
            # print(type(sr))

        elif isinstance(property, int):
            # get column index
            column_index = df.columns[property-1]
            sr = df.loc[:, column_index]
            # print(type(sr))

        else:
            raise ValueError(f"loading error! {property} is not a valid type!")

        # convert to dict
        data_dict = DataResult(**sr.to_dict())
        # print(data_dict, type(data_dict))

        # property name
        if isinstance(property, str):
            data_dict['property_name'] = property
        else:
            data_dict['property_name'] = df.columns[property-1]

        # update message
        if message:
            data_dict['message'] = str(message)
        else:
            data_dict['message'] = 'No message'

        # add databook and table name
        data_dict['databook_name'] = self.databook_name if self.databook_name else 'No databook name'
        data_dict['table_name'] = self.table_name if self.table_name else 'No table name'

        # res
        return data_dict

    def to_dict(self):
        '''
        Convert prop to dict

        Parameters
        ----------
        component_name : str
            component name

        Returns
        -------
        res : dict
            dict
        '''
        try:
            # comp data
            res = self.prop_data

            return res
        except Exception as e:
            raise Exception("Conversion failed!, ", e)

table_columns: List[str] property

Get table columns from data-table structure

Parameters

column_name : str column name (default: 'COLUMNS')

Returns

columns : list list of columns

table_structure property

Get table structure from yml file (if exists)

table_symbols: List[str] property

Get table symbols from data-table structure

Parameters

symbol_name : str symbol name (default: 'SYMBOL')

Returns

symbols : list list of symbols

table_units: List[str] property

Get table units from data-table structure

Parameters

unit_name : str unit name (default: 'UNIT')

Returns

units : list list of units

table_values property

Get table values from yml file (if exists)

__init__(databook_name, table_name, table_data, table_values=None, table_structure=None)

Initialize TableData class

Parameters

databook_name : str databook name table_name : str table name table_data : dict table data (dict), taken directly from yml file table_values : list | dict, optional table values (default: None), taken directly from yml file if exists table_structure : dict, optional table structure (default: None), taken directly from yml file if exists

Source code in pyThermoDB/core/tabledata.py

def __init__(
    self,
    databook_name,
    table_name,
    table_data,
    table_values: Optional[List | Dict] = None,
    table_structure: Optional[Dict[str, Any]] = None
):
    '''
    Initialize TableData class

    Parameters
    ----------
    databook_name : str
        databook name
    table_name : str
        table name
    table_data : dict
        table data (dict), taken directly from yml file
    table_values : list | dict, optional
        table values (default: None), taken directly from yml file if exists
    table_structure : dict, optional
        table structure (default: None), taken directly from yml file if exists
    '''
    self.databook_name = databook_name
    self.table_name = table_name
    self.table_data = table_data  # reference template (yml)
    # table values (yml)
    self.__table_values = table_values if table_values else None
    self.__table_structure = table_structure if table_structure else None

data_structure()

Display data-table structure including column names, symbol, units and values

Source code in pyThermoDB/core/tabledata.py

def data_structure(self):
    '''
    Display data-table structure including `column names`, `symbol`, `units` and `values`
    '''
    # dataframe
    df = pd.DataFrame(self.table_data)
    # add ID column
    df.insert(0, 'ID', range(1, len(df) + 1))
    # arrange columns
    # change the position of ID column to the last
    cols = df.columns.tolist()
    cols.insert(len(cols), cols.pop(cols.index('ID')))
    df = df[cols]

    return df

get_property(property, message=None)

Get a component property from data table structure

Parameters

property : str | int property name or id message : str message to display when property is found or not found

Returns

data_dict : DataResult property result dict

Source code in pyThermoDB/core/tabledata.py

def get_property(self, property: str | int, message: Optional[str] = None) -> DataResult:
    '''
    Get a component property from data table structure

    Parameters
    ----------
    property : str | int
        property name or id
    message : str
        message to display when property is found or not found

    Returns
    -------
    data_dict : DataResult
        property result dict
    '''
    # ! get data for a selected component
    # dataframe
    df = pd.DataFrame(self.prop_data)

    get_data = None
    # choose a column
    if isinstance(property, str):
        # df = df[property_name]
        # look up prop_data dict
        prop_data_keys_ = [key.lower() for key in self.prop_data.keys()]

        # NOTE: property lower
        property_ = property.lower()

        # check key exists
        if property_ in prop_data_keys_:
            # loop through prop_data dict
            for key, value in self.prop_data.items():
                # check key
                if property_ == key.lower():
                    # value found
                    get_data = self.prop_data[key]
                    # property name
                    property = key
                    break
            # get_data = self.prop_data[property]
        else:
            # NOTE: symbol
            # check symbol value in each item
            for key, value in self.prop_data.items():
                # check if property is in the symbol
                if property == value['symbol']:
                    # value found
                    get_data = self.prop_data[key]
                    # property name
                    property = key
                    break

        # ! check if property found
        if get_data is None:
            raise ValueError(f"Property '{property}' not found!")
        # series
        sr = pd.Series(get_data, dtype='str')
        # print(type(sr))

    elif isinstance(property, int):
        # get column index
        column_index = df.columns[property-1]
        sr = df.loc[:, column_index]
        # print(type(sr))

    else:
        raise ValueError(f"loading error! {property} is not a valid type!")

    # convert to dict
    data_dict = DataResult(**sr.to_dict())
    # print(data_dict, type(data_dict))

    # property name
    if isinstance(property, str):
        data_dict['property_name'] = property
    else:
        data_dict['property_name'] = df.columns[property-1]

    # update message
    if message:
        data_dict['message'] = str(message)
    else:
        data_dict['message'] = 'No message'

    # add databook and table name
    data_dict['databook_name'] = self.databook_name if self.databook_name else 'No databook name'
    data_dict['table_name'] = self.table_name if self.table_name else 'No table name'

    # res
    return data_dict

insert(property, message=None)

Get a component property from data table structure

Parameters

property : str | int property name, symbol or id message : str message to display when property is found or not found

Returns

data_dict : DataResult property result dict

Source code in pyThermoDB/core/tabledata.py

def insert(self, property: str | int, message: Optional[str] = None) -> DataResult:
    '''
    Get a component property from data table structure

    Parameters
    ----------
    property : str | int
        property name, symbol or id
    message : str
        message to display when property is found or not found

    Returns
    -------
    data_dict : DataResult
        property result dict
    '''
    # ! get data for a selected component
    # dataframe
    df = pd.DataFrame(self.prop_data)

    get_data = None
    # choose a column
    if isinstance(property, str):
        # df = df[property_name]
        # look up prop_data dict
        # check key exists
        if property in self.prop_data.keys():
            get_data = self.prop_data[property]
        else:
            # check symbol value in each item
            for key, value in self.prop_data.items():
                if property == value['symbol']:
                    # value found
                    get_data = self.prop_data[key]
                    # property name
                    property = key
                    break
        if get_data is None:
            raise ValueError(f"Property '{property}' not found!")
        # series
        sr = pd.Series(get_data, dtype='str')
        # print(type(sr))

    elif isinstance(property, int):
        # get column index
        column_index = df.columns[property-1]
        sr = df.loc[:, column_index]
        # print(type(sr))

    else:
        raise ValueError(f"loading error! {property} is not a valid type!")

    # convert to dict
    data_dict = DataResult(**sr.to_dict())
    # print(data_dict, type(data_dict))

    # property name
    if isinstance(property, str):
        data_dict['property_name'] = property
    else:
        data_dict['property_name'] = df.columns[property-1]

    # update message
    if message:
        data_dict['message'] = str(message)
    else:
        data_dict['message'] = 'No message'

    # add databook and table name
    data_dict['databook_name'] = self.databook_name if self.databook_name else 'No databook name'
    data_dict['table_name'] = self.table_name if self.table_name else 'No table name'

    # res
    return data_dict

to_dict()

Convert prop to dict

Parameters

component_name : str component name

Returns

res : dict dict

Source code in pyThermoDB/core/tabledata.py

def to_dict(self):
    '''
    Convert prop to dict

    Parameters
    ----------
    component_name : str
        component name

    Returns
    -------
    res : dict
        dict
    '''
    try:
        # comp data
        res = self.prop_data

        return res
    except Exception as e:
        raise Exception("Conversion failed!, ", e)

tablematrixequation

TableMatrixEquation

Source code in pyThermoDB/core/tablematrixequation.py

class TableMatrixEquation:
    # vars
    body = ''
    parms = {}
    args = {}
    arg_symbols = {}
    returns = {}
    return_symbols = {}
    body_integral = ''
    body_first_derivative = ''
    body_second_derivative = ''
    matrix_elements = []
    __trans_data = {}
    __prop_equation = {}
    __parms_values = {}
    # custom integral
    _custom_integral = {}
    # bulk data
    __trans_data_pack = {}

    def __init__(
        self,
        databook_name,
        table_name: str,
        equations: list,
        matrix_table=None
    ):
        # set
        self.databook_name = databook_name  # databook name
        self.table_name = table_name  # table name
        self.equations = equations  # * from reference yml
        self.matrix_table = matrix_table  # * from csv

    @property
    def trans_data_pack(self):
        return self.__trans_data_pack

    @trans_data_pack.setter
    def trans_data_pack(self, value):
        self.__trans_data_pack = value

    @property
    def trans_data(self):
        return self.__trans_data

    @trans_data.setter
    def trans_data(self, value):
        self.__trans_data = {}
        self.__trans_data = value

    @property
    def prop_equation(self):
        return self.__prop_equation

    @property
    def parms_values(self):
        return self.__parms_values

    @property
    def custom_integral(self):
        return self._custom_integral

    @property
    def summary(self):
        return {
            'eq_id': 1,
            'table_name': self.table_name,
            'args': self.args,
            'arg_symbols': self.arg_symbols,
            'parms': self.parms,
            'returns': self.returns,
            'return_symbols': self.return_symbols,
            'body': self.body,
            'body_integral': self.body_integral,
            'body_first_derivative': self.body_first_derivative,
            'body_second_derivative': self.body_second_derivative,
            'custom_integral': self._custom_integral,
            'matrix_elements': self.matrix_elements,
        }

    def eq_structure(self, id=1):
        '''
        Display equation details

        Parameters
        ----------
        id : int
            equation id - non-zero-based id (from 1 to ...), default is 1

        Returns
        -------
        eq_summary : dict
            equation summary
        '''
        try:
            # set id
            id = int(id)-1
            # equation id
            equation = self.equations[id]
            # equation body
            _body = equation['BODY']
            # equation args
            _args = equation['ARGS']
            # equation params
            _parms = equation['PARMS']
            # equation src
            _return = equation['RETURNS']
            # check if exist
            _body_integral = equation.get('BODY-INTEGRAL')
            _body_first_derivative = equation.get(
                'BODY-FIRST-DERIVATIVE')
            _body_second_derivative = equation.get(
                'BODY-SECOND-DERIVATIVE')
            # custom integral
            _custom_integral = equation.get('CUSTOM-INTEGRAL')

            # eq summary
            eq_summary = {
                'id': id,
                'body': _body,
                'args': _args,
                'parms': _parms,
                'return': _return,
                'body_integral': _body_integral,
                'body_first_derivative': _body_first_derivative,
                'body_second_derivative': _body_second_derivative,
                'custom_integral': _custom_integral
            }
            return eq_summary
        except Exception as e:
            raise Exception(f'Loading error {e}!')

    def eq_info(self):
        '''Get equation information.'''
        try:
            # get return
            _return = self.returns

            # check length
            if len(_return) == 1:
                return list(_return.values())[0]
            else:
                raise Exception("Every equation has only one return")
        except Exception as e:
            raise Exception(f'Loading error {e}!')

    def cal(
        self,
        message: str = '',
        decimal_accuracy: int = 4,
        filter_elements: list = [],
        output_format: Literal[
            'alphabetic', 'numeric'
        ] = 'numeric',
        **args
    ) -> EquationResult:
        '''
        Execute a function

        Parameters
        ----------
        message : str
            message to be printed
        decimal_accuracy : int
            decimal accuracy (default is 4)
        filter_elements : list[str], optional
            list of elements to be calculated (default is None)
        output_format : Literal['alphabetic', 'numeric'], optional
            output format, either 'alphabetic' or 'numeric' (default is 'numeric')
        args : dict
            a dictionary contains variable names and values such as T=300, P=1

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> res = cal(message='Interaction parameters of the NRTL equation',T=289.15)
        >>> print(res)
        '''
        try:
            # equation info
            eq_info = self.eq_info()

            # add table name and databook
            eq_src = {
                'table_name': self.table_name,
                'databook_name': self.databook_name,
            }
            # update
            eq_info.update(eq_src)

            # build parms dict
            # key: parms name, value: parms matrix (2d array)
            _parms = self.load_parms()
            # execute equation
            # res
            res = None
            res_comp = {}
            res_filtered = None
            res_comp_filtered = None

            # NOTE: execute equation
            res = self.eqExe(self.body, _parms, args=args)

            if res is not None:
                res = np.round(res, decimal_accuracy)

                # SECTION
                # element no
                element_no = len(self.matrix_elements)

                # extract from res
                for i in range(element_no):
                    for j in range(element_no):
                        # key
                        key = f'{self.matrix_elements[i].strip()} | {self.matrix_elements[j].strip()}'
                        # value
                        value = res[i][j]
                        # set
                        res_comp[key] = value

                # SECTION
                # check
                if len(filter_elements) != 0:
                    # check at least 2 elements
                    if len(filter_elements) < 2:
                        raise Exception('At least 2 elements required!')

                    # init
                    res_comp_filtered = {}

                    # filter
                    filtered_elements_no = len(filter_elements)

                    # init
                    res_filtered = np.zeros(
                        filtered_elements_no*filtered_elements_no)
                    k = 0

                    # extract from res
                    for element_1 in filter_elements:
                        for element_2 in filter_elements:
                            # key
                            key_ = f'{element_1.strip()} | {element_2.strip()}'
                            # value
                            value = res_comp[key_]
                            # set
                            res_comp_filtered[key_] = value
                            # set filtered value
                            res_filtered[k] = value

                            # increment
                            k += 1

                    # reshape
                    res_filtered = np.array(res_filtered).reshape(
                        filtered_elements_no, filtered_elements_no)

            # SECTION
            # set message
            if message == '':
                message = 'No message'

            # eq res
            if output_format == 'numeric':
                # set
                res_ = res_filtered if res_filtered is not None else res
            elif output_format == 'alphabetic':
                # set
                res_ = res_comp_filtered if res_comp_filtered is not None else res_comp
            else:
                raise Exception('Output format not supported!')

            eq_data = format_eq_data(res_, eq_info, message or 'No message', )

            return eq_data
        except Exception as e:
            raise Exception('Calculation failed!, ', e)

    def cal_integral(self, **args):
        '''
        Calculate integral

        Parameters
        ----------
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> # heat capacity integral
        >>> res = cal_integral(T1=120,T2=150)
        >>> print(res)
        '''
        # build parms dict
        _parms = self.load_parms()
        # execute equation
        res = self.eqExe(self.body_integral, _parms, args=args)
        return res

    def cal_custom_integral(
            self,
            equation_name: str,
            **args
    ):
        '''
        Calculate custom integral

        Parameters
        ----------
        equation_name : str
            equation name
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> res = cal_custom_integral('Cp/RT',T1=120,T2=150)
        >>> print(res)
        '''
        try:
            # check
            if equation_name is None:
                raise Exception('Equation name not defined!')

            # check equation name exists
            if equation_name not in self._custom_integral:
                raise Exception('Equation name not found!')

            # build parms dict
            _parms = self.load_parms()

            # check
            if len(self._custom_integral) > 0:
                # body
                _body_lines = self._custom_integral[equation_name]
                # stringify
                _body = ";".join(_body_lines)
            else:
                _body = None
            # execute equation
            res = self.eqExe(_body, _parms, args=args)
            return res
        except Exception as e:
            raise Exception('Loading custom integral failed!, ', e)

    def cal_first_derivative(self, **args):
        '''
        Calculate first derivative

        Parameters
        ----------
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> res = cal_first_derivative(T=120,P=1)
        >>> print(res)
        '''
        try:
            # check
            if (self.body_first_derivative is None or
                    self.body_first_derivative == 'None'):
                print('The first derivative not defined!')

            # build parms dict
            _parms = self.load_parms()
            # execute equation
            res = self.eqExe(self.body_first_derivative, _parms, args=args)
            return res
        except Exception as e:
            raise Exception("Derivation calculation failed!, ", e)

    def cal_second_derivative(self, **args):
        '''
        Calculate second derivative

        Parameters
        ----------
        args : dict
            a dictionary contains variable names and values

        Returns
        -------
        res : float
            calculation result

        Examples
        --------
        >>> res = cal_second_derivative(T=120,P=1)
        >>> print(res)
        '''
        try:
            # check
            if (self.body_second_derivative is None or
                    self.body_second_derivative == 'None'):
                print('The second derivative not defined!')

            # build parms dict
            _parms = self.load_parms()
            # execute equation
            res = self.eqExe(self.body_second_derivative, _parms, args=args)
            return res
        except Exception as e:
            raise Exception('Derivation calculation failed!, ', e)

    def get_component_info(self, column_name: str = 'Name'):
        '''
        Get component info through retrieving data from the matrix table
        Parameters
        ----------
        column_name : str
            column name to retrieve data from the matrix table (default is 'Name')

        Returns
        -------
        tuple
            component names, component index, component number
        '''
        try:
            # check
            if self.matrix_table is None:
                raise Exception('Matrix table not found!')

            # check
            if not isinstance(self.matrix_table, pd.DataFrame):
                raise Exception('Matrix table (dataframe) not found!')

            # component
            component_names = {
                name: i for i, name in enumerate(self.matrix_table[str(column_name)]) if name != '-'}
            # reset value to start from 0
            component_idx = {
                str(i): name for i, name in enumerate(component_names.keys())}

            # component no
            component_no = len(component_names)

            # res
            return component_names, component_idx, component_no
        except Exception as e:
            raise Exception('Set params matrix failed!, ', e)

    def get_matrix_table_info(
            self,
            symbol_id: int = 0,
            unit_id: int = 1
    ) -> tuple[list, list, list]:
        """
        Get matrix table info

        Parameters
        ----------
        symbol_id : int
            symbol id (default is 0)
        unit_id : int
            unit id (default is 1)

        Returns
        -------
        tuple
            column names, symbols, units
        """
        try:
            # check
            if self.matrix_table is None:
                raise Exception('Matrix table not found!')

            # check
            if not isinstance(self.matrix_table, pd.DataFrame):
                raise Exception('Matrix table (dataframe) not found!')

            # matrix table columns
            column_names = list(self.matrix_table.columns)

            # symbol
            symbols = self.matrix_table.iloc[int(
                symbol_id), :].to_list()
            # unit
            units = self.matrix_table.iloc[int(
                unit_id), :].to_list()

            # res
            return column_names, symbols, units

        except Exception as e:
            raise Exception('Get matrix table info failed!, ', e)

    def get_params_symbols(
            self,
            symbol_identifier: str = '_i_j'
    ):
        """
        Get parms symbols

        Returns
        -------
        tuple
            parms_name, parms_name_clean
        """
        try:
            #
            if isinstance(self.parms, dict):
                # loaded parms (taken from reference)
                parms_name = list(self.parms.keys())
                # params clean
                parms_name_clean = [item.split(str(symbol_identifier))[0]
                                    for item in parms_name]
            else:
                raise Exception('Parms not found!')

            # res
            return parms_name, parms_name_clean

        except Exception as e:
            raise Exception('Get params info failed!, ', e)

    def load_parms(self):
        '''
        Load parms values and store in a dict,
        These parameters are constant values defined in an equation.
        '''
        try:
            # trans data (taken from csv)
            trans_data_pack = self.trans_data_pack
            # component names
            component_names = list(trans_data_pack.keys())
            # strip
            component_names = [item.strip() for item in component_names]
            # set
            self.matrix_elements = component_names

            # TODO
            # * check duplicated names
            if len(component_names) != len(set(component_names)):
                raise Exception('Duplicated component names found!')

            # component no
            component_no = len(component_names)

            # TODO
            # * check if component no is 1
            if component_no == 1:
                raise Exception('Only one component found!')

            # check
            if not isinstance(self.matrix_table, pd.DataFrame):
                raise Exception('Matrix table not found!')

            # ! matrix table info
            matrix_table_columns, matrix_table_data_symbol, matrix_table_data_unit = self.get_matrix_table_info()

            # ! component names in the matrix_table
            matrix_table_data_component_names, matrix_table_data_component_names_idx, matrix_table_data_component_names_no = self.get_component_info()

            # TODO: check component in matrix-table
            for component in component_names:
                if component not in matrix_table_data_component_names:
                    raise Exception('Component not found!')

            # check component name id
            component_names_dict = {}
            for i, name in matrix_table_data_component_names_idx.items():
                if name in component_names:
                    component_names_dict[i] = name

            component_names_idx = list(component_names_dict.keys())
            component_names_idx = [int(item) for item in component_names_idx]

            # check
            if component_no > matrix_table_data_component_names_no:
                raise Exception("Check component number!")

            # get parms symbols
            parms_name, parms_name_clean = self.get_params_symbols('_i_j')

            # ! parms column index in the dataframe
            # params column index
            # parms_col_index = []
            # looping through
            # for item in matrix_table_columns:
            #     if item.split('_')[0] in parms_name_clean:
            #         parms_col_index.append(
            #             matrix_table_columns.index(item))

            parms_col_index = []
            # looping through clean parms names
            for item in parms_name_clean:
                # build parms symbol
                # create regex
                # regex = re.compile(re.escape(item) + '_')
                # create str pattern
                str_pattern = item + '_'

                for matrix_table_column in matrix_table_columns:
                    # check
                    # * method 1: using regex
                    # if regex.search(matrix_table_column):
                    #     # get index
                    #     index = matrix_table_columns.index(matrix_table_column)
                    #     # save
                    #     parms_col_index.append(index)

                    # * method 2: using startswith
                    if matrix_table_column.startswith(str_pattern):
                        # get index
                        index = matrix_table_columns.index(matrix_table_column)
                        # save
                        parms_col_index.append(index)

            # create matrix
            parms_matrix_list = {}
            # component data
            matrix_table_component_data = {}
            # parms data
            matrix_table_component_parms_data = {}
            # looping through matrix table data
            for i, (component_key, component) in enumerate(matrix_table_data_component_names_idx.items()):
                # component data
                _data_get = self.matrix_table[self.matrix_table['Name'].str.match(
                    component, case=False, na=False)]

                # set
                _row_index = int(_data_get.index[0])
                _data = _data_get.to_dict(orient='records')[0]

                # update
                _data['row_index'] = _row_index

                # check
                if len(_data) == 0:
                    raise Exception('Component data not found!')

                # component parms data
                matrix_table_component_parms_data[component] = {}
                # looping through self.parms
                # rename _data keys
                # * method 1:
                for key, value in _data.items():
                    # find parms
                    for item in parms_name_clean:
                        _find_key = str(key).find(item+'_i')
                        # check
                        if _find_key != -1:
                            # new key
                            _new_key = str(key).replace('i', str(i+1))
                            # log
                            # print("method 1: ", _new_key, value, component)

                            # set value
                            # matrix_table_component_parms_data[component][str(
                            #     _new_key)] = float(value)

                # * method 2:
                # find parms from matrix column index
                # set
                jj = 0
                for item in parms_col_index:
                    # check
                    if jj > matrix_table_data_component_names_no-1:
                        jj = 0
                    # lopping through data
                    for ii, (key, value) in enumerate(_data.items()):
                        # check
                        if ii == item:
                            # print(ii, item, jj)
                            # new key
                            _new_key = str(key).split(
                                "_")[0]+"_"+f"{i+1}"+"_"+f"{jj+1}"

                            # set unit
                            _unit = float(
                                matrix_table_data_unit[ii] or 1)

                            # log
                            # print("method 2: ", _new_key, value, component)
                            # set value
                            matrix_table_component_parms_data[component][_new_key] = float(
                                value)/_unit
                            # reset
                            jj = jj+1

                matrix_table_component_data[component] = _data

            # looping through parms group
            for i in range(len(parms_name_clean)):

                # parms key (such as A_i_j)
                _parms_name = parms_name_clean[i]
                _parms_key = f'{_parms_name}_i_j'

                # 2d array
                # _2d_array = np.zeros(
                #     (component_no, component_no))

                # 2d list
                _2d_list = []

                # looping through component
                for j in range(matrix_table_data_component_names_no):

                    # check
                    if j in component_names_idx:
                        # check component exists in
                        _component = matrix_table_data_component_names_idx[str(
                            j)]

                        # get component data
                        _data = matrix_table_component_data[_component]

                        # get component parms data
                        _parms_data = matrix_table_component_parms_data[_component]

                        # looping through component
                        for k in range(matrix_table_data_component_names_no):
                            # set key
                            _key = f'{_parms_name}_{j+1}_{k+1}'

                            # check
                            if k in component_names_idx:
                                # fill 2d array
                                # _2d_array[j, k] = float(_parms_data[_key])
                                _2d_list.append(float(_parms_data[_key]))

                # reshape list
                _2d_array = np.array(_2d_list).reshape(
                    component_no, component_no)
                # save parms matrix
                parms_matrix_list[_parms_key] = _2d_array

            # log
            # print("A_i_j: ", parms_matrix_list['A_i_j'])
            # print("B_i_j: ", parms_matrix_list['B_i_j'])

            # res
            return parms_matrix_list
        except Exception as e:
            raise Exception("Loading equation parameters failed!, ", e)

    def equation_body(self):
        '''
        Display equation body

        Parameters
        ----------
        None

        Returns
        -------
        body : str
            equation body
        '''
        return self.body

    def equation_parms(self, dataframe=True):
        '''
        Display equation parms

        Parameters
        ----------
        value : bool, optional
            DESCRIPTION. The default is True.

        Returns
        -------
        df : dataframe
            equation parms
        '''
        df = pd.DataFrame(self.parms)

        if dataframe:
            return df
        else:
            return self.parms

    def equation_args(self, dataframe=True):
        '''
        Display equation args,

        Parameters
        ----------
        value : bool, optional
            DESCRIPTION. The default is True.

        Returns
        -------
        df : dataframe
            equation args
        '''
        df = pd.DataFrame(self.args)

        if dataframe:
            return df
        else:
            return self.args

    def equation_return(self, dataframe=True):
        '''
        Display equation return,

        Parameters
        ----------
        value : bool, optional
            DESCRIPTION. The default is True.


        Returns
        -------
        df : dataframe
            equation return
        '''
        df = pd.DataFrame(self.returns)

        if dataframe:
            return df
        else:
            return self.returns

    def eqSet(self):
        '''
        Set the equation used for calculation

        Parameters
        ----------
        transform_api_data : dict
            transform api data

        Returns
        -------
        None.

        Notes
        ------
        Only one equation is used for matrix-equation calculation which is denoted by Eq 1.
        '''
        # set
        # transform_api_data = self.trans_data_pack

        # eq
        Eq_data = 0
        # Eq_data = int(transform_api_data['Eq']['value'])

        # load equation
        eq_summary = self.eq_structure(Eq_data)

        # extract data
        _body = eq_summary['body']
        self.body = ';'.join(_body)
        # check
        if eq_summary['parms'] is not None:
            self.parms = eq_summary['parms']
        else:
            self.parms = []
        # check
        if eq_summary['args'] is not None:
            self.args = eq_summary['args']
            # make arg symbols
            self.arg_symbols = self.make_arg_symbols(self.args)
        else:
            self.args = []
        # check
        if eq_summary['return'] is not None:
            self.returns = eq_summary['return']
            # make return symbols
            self.return_symbols = self.make_return_symbols(self.returns)
        else:
            self.returns = []
        # integral
        body_integral = eq_summary['body_integral']
        # check
        if body_integral is not None and body_integral != 'None':
            self.body_integral = ";".join(body_integral)
        else:
            self.body_integral = None
        # first derivative
        first_derivative = eq_summary['body_first_derivative']
        # check
        if first_derivative is not None and first_derivative != 'None':
            self.body_first_derivative = ";".join(first_derivative)
        else:
            self.body_first_derivative = None
        # second derivative
        second_derivative = eq_summary['body_second_derivative']
        # check
        if second_derivative is not None and second_derivative != 'None':
            self.body_second_derivative = ";".join(second_derivative)
        else:
            self.body_second_derivative = None
        # custom integral
        custom_integral = eq_summary['custom_integral']
        # check
        if custom_integral is not None and custom_integral != 'None':
            self._custom_integral = custom_integral
        else:
            self._custom_integral = {}

        # update __prop_equation
        self.__prop_equation = {
            'BODY': self.body,
            'PARMS': self.parms,
            'ARGS': self.args,
            'RETURNS': self.returns,
            'BODY-INTEGRAL': self.body_integral,
            'BODY-FIRST-DERIVATIVE': self.body_first_derivative,
            'BODY-SECOND-DERIVATIVE': self.body_second_derivative,
            'CUSTOM-INTEGRAL': self._custom_integral
        }

        # check params
        if len(self.parms) > 0:
            self.__parms_values = self.load_parms()

    def eqExe(
            self,
            body,
            parms,
            args
    ):
        '''
        Execute a function body with provided arguments and parameters.

        Parameters
        ----------
        body : str
            A string containing Python code to execute. Must define a variable `res` for the return value.
        parms : dict
            A dictionary of parameters accessible as `parms` in the function body.
        args : dict
            A dictionary of arguments accessible as `args` in the function body.

        Returns
        -------
        res : float
            The calculation result defined in the `body` (if `res` is set), or None in case of errors.
        '''
        # check body
        if body is None:
            raise Exception('Function body not defined!')

        try:
            # Define a namespace dictionary for eval
            namespace = {'args': args, "parms": parms}
            # Import math module and numpy (np) lib within the function
            namespace['np'] = np
            namespace['math'] = math
            # Execute the body within the namespace
            exec(body, namespace)
            # Return the result
            return namespace['res']
        except Exception as e:
            raise Exception("Calculation failed!, ", e)

    def to_dict(self):
        '''
        Convert equation to dict

        Parameters
        ----------
        None.

        Returns
        -------
        res : str
            equation in dict
        '''
        # create dict
        res = self.__prop_equation
        # yml
        # _eq_yml = _eq
        # convert to yml
        # res = yaml.dump(_eq_yml)

        return res

    def check_custom_integral_equation_body(self, equation_name: str) -> str:
        '''
        Displays the equation body of custom integral by equation name

        Parameters
        ----------
        equation_name : str
            equation name

        Returns
        -------
        body : str
            equation body

        Examples
        --------
        >>> body = custom_integral_equation_body('Cp/RT')
        '''
        try:
            # check
            if self._custom_integral is None:
                raise Exception('Custom integral not defined!')

            if equation_name is None:
                raise Exception('Equation name not defined!')

            if equation_name not in self._custom_integral:
                raise Exception('Equation name not found!')
            # get equation body
            body = self._custom_integral.get(equation_name, 'None')
            return body
        except Exception as e:
            raise Exception("Loading custom integral body failed!, ", e)

    def make_arg_symbols(self, args) -> dict:
        '''
        Make argument symbols

        Parameters
        ----------
        args : dict
            arguments

        Returns
        -------
        None.
        '''
        try:
            # reset
            arg_symbols = {}

            # check
            if args is not None:
                if isinstance(args, dict):
                    for key, value in args.items():
                        # symbol
                        _symbol = args[key].get('symbol')
                        # set
                        arg_symbols[_symbol] = {
                            'name': args[key].get('name'),
                            'symbol': _symbol,
                            'unit': args[key].get('unit'),
                        }

                    # return
                    return arg_symbols

            return {}
        except Exception as e:
            raise Exception("Making argument symbols failed!, ", e)

    def make_return_symbols(self, returns) -> dict:
        '''
        Make return symbols

        Parameters
        ----------
        returns : dict
            returns

        Returns
        -------
        None.
        '''
        try:
            # reset
            return_symbols = {}

            # check
            if returns is not None:
                if isinstance(returns, dict):
                    for key, value in returns.items():
                        # symbol
                        _symbol = returns[key].get('symbol')
                        # set
                        return_symbols[_symbol] = {
                            'name': returns[key].get('name'),
                            'symbol': _symbol,
                            'unit': returns[key].get('unit'),
                        }

                # return
                return return_symbols

            return {}
        except Exception as e:
            raise Exception("Making return symbols failed!, ", e)

cal(message='', decimal_accuracy=4, filter_elements=[], output_format='numeric', **args)

Execute a function

Parameters

message : str message to be printed decimal_accuracy : int decimal accuracy (default is 4) filter_elements : list[str], optional list of elements to be calculated (default is None) output_format : Literal['alphabetic', 'numeric'], optional output format, either 'alphabetic' or 'numeric' (default is 'numeric') args : dict a dictionary contains variable names and values such as T=300, P=1

Returns

res : float calculation result

Examples

res = cal(message='Interaction parameters of the NRTL equation',T=289.15) print(res)

Source code in pyThermoDB/core/tablematrixequation.py

def cal(
    self,
    message: str = '',
    decimal_accuracy: int = 4,
    filter_elements: list = [],
    output_format: Literal[
        'alphabetic', 'numeric'
    ] = 'numeric',
    **args
) -> EquationResult:
    '''
    Execute a function

    Parameters
    ----------
    message : str
        message to be printed
    decimal_accuracy : int
        decimal accuracy (default is 4)
    filter_elements : list[str], optional
        list of elements to be calculated (default is None)
    output_format : Literal['alphabetic', 'numeric'], optional
        output format, either 'alphabetic' or 'numeric' (default is 'numeric')
    args : dict
        a dictionary contains variable names and values such as T=300, P=1

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> res = cal(message='Interaction parameters of the NRTL equation',T=289.15)
    >>> print(res)
    '''
    try:
        # equation info
        eq_info = self.eq_info()

        # add table name and databook
        eq_src = {
            'table_name': self.table_name,
            'databook_name': self.databook_name,
        }
        # update
        eq_info.update(eq_src)

        # build parms dict
        # key: parms name, value: parms matrix (2d array)
        _parms = self.load_parms()
        # execute equation
        # res
        res = None
        res_comp = {}
        res_filtered = None
        res_comp_filtered = None

        # NOTE: execute equation
        res = self.eqExe(self.body, _parms, args=args)

        if res is not None:
            res = np.round(res, decimal_accuracy)

            # SECTION
            # element no
            element_no = len(self.matrix_elements)

            # extract from res
            for i in range(element_no):
                for j in range(element_no):
                    # key
                    key = f'{self.matrix_elements[i].strip()} | {self.matrix_elements[j].strip()}'
                    # value
                    value = res[i][j]
                    # set
                    res_comp[key] = value

            # SECTION
            # check
            if len(filter_elements) != 0:
                # check at least 2 elements
                if len(filter_elements) < 2:
                    raise Exception('At least 2 elements required!')

                # init
                res_comp_filtered = {}

                # filter
                filtered_elements_no = len(filter_elements)

                # init
                res_filtered = np.zeros(
                    filtered_elements_no*filtered_elements_no)
                k = 0

                # extract from res
                for element_1 in filter_elements:
                    for element_2 in filter_elements:
                        # key
                        key_ = f'{element_1.strip()} | {element_2.strip()}'
                        # value
                        value = res_comp[key_]
                        # set
                        res_comp_filtered[key_] = value
                        # set filtered value
                        res_filtered[k] = value

                        # increment
                        k += 1

                # reshape
                res_filtered = np.array(res_filtered).reshape(
                    filtered_elements_no, filtered_elements_no)

        # SECTION
        # set message
        if message == '':
            message = 'No message'

        # eq res
        if output_format == 'numeric':
            # set
            res_ = res_filtered if res_filtered is not None else res
        elif output_format == 'alphabetic':
            # set
            res_ = res_comp_filtered if res_comp_filtered is not None else res_comp
        else:
            raise Exception('Output format not supported!')

        eq_data = format_eq_data(res_, eq_info, message or 'No message', )

        return eq_data
    except Exception as e:
        raise Exception('Calculation failed!, ', e)

cal_custom_integral(equation_name, **args)

Calculate custom integral

Parameters

equation_name : str equation name args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

res = cal_custom_integral('Cp/RT',T1=120,T2=150) print(res)

Source code in pyThermoDB/core/tablematrixequation.py

def cal_custom_integral(
        self,
        equation_name: str,
        **args
):
    '''
    Calculate custom integral

    Parameters
    ----------
    equation_name : str
        equation name
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> res = cal_custom_integral('Cp/RT',T1=120,T2=150)
    >>> print(res)
    '''
    try:
        # check
        if equation_name is None:
            raise Exception('Equation name not defined!')

        # check equation name exists
        if equation_name not in self._custom_integral:
            raise Exception('Equation name not found!')

        # build parms dict
        _parms = self.load_parms()

        # check
        if len(self._custom_integral) > 0:
            # body
            _body_lines = self._custom_integral[equation_name]
            # stringify
            _body = ";".join(_body_lines)
        else:
            _body = None
        # execute equation
        res = self.eqExe(_body, _parms, args=args)
        return res
    except Exception as e:
        raise Exception('Loading custom integral failed!, ', e)

cal_first_derivative(**args)

Calculate first derivative

Parameters

args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

res = cal_first_derivative(T=120,P=1) print(res)

Source code in pyThermoDB/core/tablematrixequation.py

def cal_first_derivative(self, **args):
    '''
    Calculate first derivative

    Parameters
    ----------
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> res = cal_first_derivative(T=120,P=1)
    >>> print(res)
    '''
    try:
        # check
        if (self.body_first_derivative is None or
                self.body_first_derivative == 'None'):
            print('The first derivative not defined!')

        # build parms dict
        _parms = self.load_parms()
        # execute equation
        res = self.eqExe(self.body_first_derivative, _parms, args=args)
        return res
    except Exception as e:
        raise Exception("Derivation calculation failed!, ", e)

cal_integral(**args)

Calculate integral

Parameters

args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

heat capacity integral

res = cal_integral(T1=120,T2=150) print(res)

Source code in pyThermoDB/core/tablematrixequation.py

def cal_integral(self, **args):
    '''
    Calculate integral

    Parameters
    ----------
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> # heat capacity integral
    >>> res = cal_integral(T1=120,T2=150)
    >>> print(res)
    '''
    # build parms dict
    _parms = self.load_parms()
    # execute equation
    res = self.eqExe(self.body_integral, _parms, args=args)
    return res

cal_second_derivative(**args)

Calculate second derivative

Parameters

args : dict a dictionary contains variable names and values

Returns

res : float calculation result

Examples

res = cal_second_derivative(T=120,P=1) print(res)

Source code in pyThermoDB/core/tablematrixequation.py

def cal_second_derivative(self, **args):
    '''
    Calculate second derivative

    Parameters
    ----------
    args : dict
        a dictionary contains variable names and values

    Returns
    -------
    res : float
        calculation result

    Examples
    --------
    >>> res = cal_second_derivative(T=120,P=1)
    >>> print(res)
    '''
    try:
        # check
        if (self.body_second_derivative is None or
                self.body_second_derivative == 'None'):
            print('The second derivative not defined!')

        # build parms dict
        _parms = self.load_parms()
        # execute equation
        res = self.eqExe(self.body_second_derivative, _parms, args=args)
        return res
    except Exception as e:
        raise Exception('Derivation calculation failed!, ', e)

check_custom_integral_equation_body(equation_name)

Displays the equation body of custom integral by equation name

Parameters

equation_name : str equation name

Returns

body : str equation body

Examples

body = custom_integral_equation_body('Cp/RT')

Source code in pyThermoDB/core/tablematrixequation.py

def check_custom_integral_equation_body(self, equation_name: str) -> str:
    '''
    Displays the equation body of custom integral by equation name

    Parameters
    ----------
    equation_name : str
        equation name

    Returns
    -------
    body : str
        equation body

    Examples
    --------
    >>> body = custom_integral_equation_body('Cp/RT')
    '''
    try:
        # check
        if self._custom_integral is None:
            raise Exception('Custom integral not defined!')

        if equation_name is None:
            raise Exception('Equation name not defined!')

        if equation_name not in self._custom_integral:
            raise Exception('Equation name not found!')
        # get equation body
        body = self._custom_integral.get(equation_name, 'None')
        return body
    except Exception as e:
        raise Exception("Loading custom integral body failed!, ", e)

eqExe(body, parms, args)

Execute a function body with provided arguments and parameters.

Parameters

body : str A string containing Python code to execute. Must define a variable res for the return value. parms : dict A dictionary of parameters accessible as parms in the function body. args : dict A dictionary of arguments accessible as args in the function body.

Returns

res : float The calculation result defined in the body (if res is set), or None in case of errors.

Source code in pyThermoDB/core/tablematrixequation.py

def eqExe(
        self,
        body,
        parms,
        args
):
    '''
    Execute a function body with provided arguments and parameters.

    Parameters
    ----------
    body : str
        A string containing Python code to execute. Must define a variable `res` for the return value.
    parms : dict
        A dictionary of parameters accessible as `parms` in the function body.
    args : dict
        A dictionary of arguments accessible as `args` in the function body.

    Returns
    -------
    res : float
        The calculation result defined in the `body` (if `res` is set), or None in case of errors.
    '''
    # check body
    if body is None:
        raise Exception('Function body not defined!')

    try:
        # Define a namespace dictionary for eval
        namespace = {'args': args, "parms": parms}
        # Import math module and numpy (np) lib within the function
        namespace['np'] = np
        namespace['math'] = math
        # Execute the body within the namespace
        exec(body, namespace)
        # Return the result
        return namespace['res']
    except Exception as e:
        raise Exception("Calculation failed!, ", e)

eqSet()

Set the equation used for calculation

Parameters

transform_api_data : dict transform api data

Returns

None.

Notes

Only one equation is used for matrix-equation calculation which is denoted by Eq 1.

Source code in pyThermoDB/core/tablematrixequation.py

def eqSet(self):
    '''
    Set the equation used for calculation

    Parameters
    ----------
    transform_api_data : dict
        transform api data

    Returns
    -------
    None.

    Notes
    ------
    Only one equation is used for matrix-equation calculation which is denoted by Eq 1.
    '''
    # set
    # transform_api_data = self.trans_data_pack

    # eq
    Eq_data = 0
    # Eq_data = int(transform_api_data['Eq']['value'])

    # load equation
    eq_summary = self.eq_structure(Eq_data)

    # extract data
    _body = eq_summary['body']
    self.body = ';'.join(_body)
    # check
    if eq_summary['parms'] is not None:
        self.parms = eq_summary['parms']
    else:
        self.parms = []
    # check
    if eq_summary['args'] is not None:
        self.args = eq_summary['args']
        # make arg symbols
        self.arg_symbols = self.make_arg_symbols(self.args)
    else:
        self.args = []
    # check
    if eq_summary['return'] is not None:
        self.returns = eq_summary['return']
        # make return symbols
        self.return_symbols = self.make_return_symbols(self.returns)
    else:
        self.returns = []
    # integral
    body_integral = eq_summary['body_integral']
    # check
    if body_integral is not None and body_integral != 'None':
        self.body_integral = ";".join(body_integral)
    else:
        self.body_integral = None
    # first derivative
    first_derivative = eq_summary['body_first_derivative']
    # check
    if first_derivative is not None and first_derivative != 'None':
        self.body_first_derivative = ";".join(first_derivative)
    else:
        self.body_first_derivative = None
    # second derivative
    second_derivative = eq_summary['body_second_derivative']
    # check
    if second_derivative is not None and second_derivative != 'None':
        self.body_second_derivative = ";".join(second_derivative)
    else:
        self.body_second_derivative = None
    # custom integral
    custom_integral = eq_summary['custom_integral']
    # check
    if custom_integral is not None and custom_integral != 'None':
        self._custom_integral = custom_integral
    else:
        self._custom_integral = {}

    # update __prop_equation
    self.__prop_equation = {
        'BODY': self.body,
        'PARMS': self.parms,
        'ARGS': self.args,
        'RETURNS': self.returns,
        'BODY-INTEGRAL': self.body_integral,
        'BODY-FIRST-DERIVATIVE': self.body_first_derivative,
        'BODY-SECOND-DERIVATIVE': self.body_second_derivative,
        'CUSTOM-INTEGRAL': self._custom_integral
    }

    # check params
    if len(self.parms) > 0:
        self.__parms_values = self.load_parms()

eq_info()

Get equation information.

Source code in pyThermoDB/core/tablematrixequation.py

def eq_info(self):
    '''Get equation information.'''
    try:
        # get return
        _return = self.returns

        # check length
        if len(_return) == 1:
            return list(_return.values())[0]
        else:
            raise Exception("Every equation has only one return")
    except Exception as e:
        raise Exception(f'Loading error {e}!')

eq_structure(id=1)

Display equation details

Parameters

id : int equation id - non-zero-based id (from 1 to ...), default is 1

Returns

eq_summary : dict equation summary

Source code in pyThermoDB/core/tablematrixequation.py

def eq_structure(self, id=1):
    '''
    Display equation details

    Parameters
    ----------
    id : int
        equation id - non-zero-based id (from 1 to ...), default is 1

    Returns
    -------
    eq_summary : dict
        equation summary
    '''
    try:
        # set id
        id = int(id)-1
        # equation id
        equation = self.equations[id]
        # equation body
        _body = equation['BODY']
        # equation args
        _args = equation['ARGS']
        # equation params
        _parms = equation['PARMS']
        # equation src
        _return = equation['RETURNS']
        # check if exist
        _body_integral = equation.get('BODY-INTEGRAL')
        _body_first_derivative = equation.get(
            'BODY-FIRST-DERIVATIVE')
        _body_second_derivative = equation.get(
            'BODY-SECOND-DERIVATIVE')
        # custom integral
        _custom_integral = equation.get('CUSTOM-INTEGRAL')

        # eq summary
        eq_summary = {
            'id': id,
            'body': _body,
            'args': _args,
            'parms': _parms,
            'return': _return,
            'body_integral': _body_integral,
            'body_first_derivative': _body_first_derivative,
            'body_second_derivative': _body_second_derivative,
            'custom_integral': _custom_integral
        }
        return eq_summary
    except Exception as e:
        raise Exception(f'Loading error {e}!')

equation_args(dataframe=True)

Display equation args,

Parameters

value : bool, optional DESCRIPTION. The default is True.

Returns

df : dataframe equation args

Source code in pyThermoDB/core/tablematrixequation.py

def equation_args(self, dataframe=True):
    '''
    Display equation args,

    Parameters
    ----------
    value : bool, optional
        DESCRIPTION. The default is True.

    Returns
    -------
    df : dataframe
        equation args
    '''
    df = pd.DataFrame(self.args)

    if dataframe:
        return df
    else:
        return self.args

equation_body()

Display equation body

Parameters

None

Returns

body : str equation body

Source code in pyThermoDB/core/tablematrixequation.py

def equation_body(self):
    '''
    Display equation body

    Parameters
    ----------
    None

    Returns
    -------
    body : str
        equation body
    '''
    return self.body

equation_parms(dataframe=True)

Display equation parms

Parameters

value : bool, optional DESCRIPTION. The default is True.

Returns

df : dataframe equation parms

Source code in pyThermoDB/core/tablematrixequation.py

def equation_parms(self, dataframe=True):
    '''
    Display equation parms

    Parameters
    ----------
    value : bool, optional
        DESCRIPTION. The default is True.

    Returns
    -------
    df : dataframe
        equation parms
    '''
    df = pd.DataFrame(self.parms)

    if dataframe:
        return df
    else:
        return self.parms

equation_return(dataframe=True)

Display equation return,

Parameters

value : bool, optional DESCRIPTION. The default is True.

Returns

df : dataframe equation return

Source code in pyThermoDB/core/tablematrixequation.py

def equation_return(self, dataframe=True):
    '''
    Display equation return,

    Parameters
    ----------
    value : bool, optional
        DESCRIPTION. The default is True.


    Returns
    -------
    df : dataframe
        equation return
    '''
    df = pd.DataFrame(self.returns)

    if dataframe:
        return df
    else:
        return self.returns

get_component_info(column_name='Name')

Get component info through retrieving data from the matrix table Parameters

---

column_name : str column name to retrieve data from the matrix table (default is 'Name')

Returns

tuple component names, component index, component number

Source code in pyThermoDB/core/tablematrixequation.py

def get_component_info(self, column_name: str = 'Name'):
    '''
    Get component info through retrieving data from the matrix table
    Parameters
    ----------
    column_name : str
        column name to retrieve data from the matrix table (default is 'Name')

    Returns
    -------
    tuple
        component names, component index, component number
    '''
    try:
        # check
        if self.matrix_table is None:
            raise Exception('Matrix table not found!')

        # check
        if not isinstance(self.matrix_table, pd.DataFrame):
            raise Exception('Matrix table (dataframe) not found!')

        # component
        component_names = {
            name: i for i, name in enumerate(self.matrix_table[str(column_name)]) if name != '-'}
        # reset value to start from 0
        component_idx = {
            str(i): name for i, name in enumerate(component_names.keys())}

        # component no
        component_no = len(component_names)

        # res
        return component_names, component_idx, component_no
    except Exception as e:
        raise Exception('Set params matrix failed!, ', e)

get_matrix_table_info(symbol_id=0, unit_id=1)

Get matrix table info

Parameters

symbol_id : int symbol id (default is 0) unit_id : int unit id (default is 1)

Returns

tuple column names, symbols, units

Source code in pyThermoDB/core/tablematrixequation.py

def get_matrix_table_info(
        self,
        symbol_id: int = 0,
        unit_id: int = 1
) -> tuple[list, list, list]:
    """
    Get matrix table info

    Parameters
    ----------
    symbol_id : int
        symbol id (default is 0)
    unit_id : int
        unit id (default is 1)

    Returns
    -------
    tuple
        column names, symbols, units
    """
    try:
        # check
        if self.matrix_table is None:
            raise Exception('Matrix table not found!')

        # check
        if not isinstance(self.matrix_table, pd.DataFrame):
            raise Exception('Matrix table (dataframe) not found!')

        # matrix table columns
        column_names = list(self.matrix_table.columns)

        # symbol
        symbols = self.matrix_table.iloc[int(
            symbol_id), :].to_list()
        # unit
        units = self.matrix_table.iloc[int(
            unit_id), :].to_list()

        # res
        return column_names, symbols, units

    except Exception as e:
        raise Exception('Get matrix table info failed!, ', e)

get_params_symbols(symbol_identifier='_i_j')

Get parms symbols

Returns

tuple parms_name, parms_name_clean

Source code in pyThermoDB/core/tablematrixequation.py

def get_params_symbols(
        self,
        symbol_identifier: str = '_i_j'
):
    """
    Get parms symbols

    Returns
    -------
    tuple
        parms_name, parms_name_clean
    """
    try:
        #
        if isinstance(self.parms, dict):
            # loaded parms (taken from reference)
            parms_name = list(self.parms.keys())
            # params clean
            parms_name_clean = [item.split(str(symbol_identifier))[0]
                                for item in parms_name]
        else:
            raise Exception('Parms not found!')

        # res
        return parms_name, parms_name_clean

    except Exception as e:
        raise Exception('Get params info failed!, ', e)

load_parms()

Load parms values and store in a dict, These parameters are constant values defined in an equation.

Source code in pyThermoDB/core/tablematrixequation.py

def load_parms(self):
    '''
    Load parms values and store in a dict,
    These parameters are constant values defined in an equation.
    '''
    try:
        # trans data (taken from csv)
        trans_data_pack = self.trans_data_pack
        # component names
        component_names = list(trans_data_pack.keys())
        # strip
        component_names = [item.strip() for item in component_names]
        # set
        self.matrix_elements = component_names

        # TODO
        # * check duplicated names
        if len(component_names) != len(set(component_names)):
            raise Exception('Duplicated component names found!')

        # component no
        component_no = len(component_names)

        # TODO
        # * check if component no is 1
        if component_no == 1:
            raise Exception('Only one component found!')

        # check
        if not isinstance(self.matrix_table, pd.DataFrame):
            raise Exception('Matrix table not found!')

        # ! matrix table info
        matrix_table_columns, matrix_table_data_symbol, matrix_table_data_unit = self.get_matrix_table_info()

        # ! component names in the matrix_table
        matrix_table_data_component_names, matrix_table_data_component_names_idx, matrix_table_data_component_names_no = self.get_component_info()

        # TODO: check component in matrix-table
        for component in component_names:
            if component not in matrix_table_data_component_names:
                raise Exception('Component not found!')

        # check component name id
        component_names_dict = {}
        for i, name in matrix_table_data_component_names_idx.items():
            if name in component_names:
                component_names_dict[i] = name

        component_names_idx = list(component_names_dict.keys())
        component_names_idx = [int(item) for item in component_names_idx]

        # check
        if component_no > matrix_table_data_component_names_no:
            raise Exception("Check component number!")

        # get parms symbols
        parms_name, parms_name_clean = self.get_params_symbols('_i_j')

        # ! parms column index in the dataframe
        # params column index
        # parms_col_index = []
        # looping through
        # for item in matrix_table_columns:
        #     if item.split('_')[0] in parms_name_clean:
        #         parms_col_index.append(
        #             matrix_table_columns.index(item))

        parms_col_index = []
        # looping through clean parms names
        for item in parms_name_clean:
            # build parms symbol
            # create regex
            # regex = re.compile(re.escape(item) + '_')
            # create str pattern
            str_pattern = item + '_'

            for matrix_table_column in matrix_table_columns:
                # check
                # * method 1: using regex
                # if regex.search(matrix_table_column):
                #     # get index
                #     index = matrix_table_columns.index(matrix_table_column)
                #     # save
                #     parms_col_index.append(index)

                # * method 2: using startswith
                if matrix_table_column.startswith(str_pattern):
                    # get index
                    index = matrix_table_columns.index(matrix_table_column)
                    # save
                    parms_col_index.append(index)

        # create matrix
        parms_matrix_list = {}
        # component data
        matrix_table_component_data = {}
        # parms data
        matrix_table_component_parms_data = {}
        # looping through matrix table data
        for i, (component_key, component) in enumerate(matrix_table_data_component_names_idx.items()):
            # component data
            _data_get = self.matrix_table[self.matrix_table['Name'].str.match(
                component, case=False, na=False)]

            # set
            _row_index = int(_data_get.index[0])
            _data = _data_get.to_dict(orient='records')[0]

            # update
            _data['row_index'] = _row_index

            # check
            if len(_data) == 0:
                raise Exception('Component data not found!')

            # component parms data
            matrix_table_component_parms_data[component] = {}
            # looping through self.parms
            # rename _data keys
            # * method 1:
            for key, value in _data.items():
                # find parms
                for item in parms_name_clean:
                    _find_key = str(key).find(item+'_i')
                    # check
                    if _find_key != -1:
                        # new key
                        _new_key = str(key).replace('i', str(i+1))
                        # log
                        # print("method 1: ", _new_key, value, component)

                        # set value
                        # matrix_table_component_parms_data[component][str(
                        #     _new_key)] = float(value)

            # * method 2:
            # find parms from matrix column index
            # set
            jj = 0
            for item in parms_col_index:
                # check
                if jj > matrix_table_data_component_names_no-1:
                    jj = 0
                # lopping through data
                for ii, (key, value) in enumerate(_data.items()):
                    # check
                    if ii == item:
                        # print(ii, item, jj)
                        # new key
                        _new_key = str(key).split(
                            "_")[0]+"_"+f"{i+1}"+"_"+f"{jj+1}"

                        # set unit
                        _unit = float(
                            matrix_table_data_unit[ii] or 1)

                        # log
                        # print("method 2: ", _new_key, value, component)
                        # set value
                        matrix_table_component_parms_data[component][_new_key] = float(
                            value)/_unit
                        # reset
                        jj = jj+1

            matrix_table_component_data[component] = _data

        # looping through parms group
        for i in range(len(parms_name_clean)):

            # parms key (such as A_i_j)
            _parms_name = parms_name_clean[i]
            _parms_key = f'{_parms_name}_i_j'

            # 2d array
            # _2d_array = np.zeros(
            #     (component_no, component_no))

            # 2d list
            _2d_list = []

            # looping through component
            for j in range(matrix_table_data_component_names_no):

                # check
                if j in component_names_idx:
                    # check component exists in
                    _component = matrix_table_data_component_names_idx[str(
                        j)]

                    # get component data
                    _data = matrix_table_component_data[_component]

                    # get component parms data
                    _parms_data = matrix_table_component_parms_data[_component]

                    # looping through component
                    for k in range(matrix_table_data_component_names_no):
                        # set key
                        _key = f'{_parms_name}_{j+1}_{k+1}'

                        # check
                        if k in component_names_idx:
                            # fill 2d array
                            # _2d_array[j, k] = float(_parms_data[_key])
                            _2d_list.append(float(_parms_data[_key]))

            # reshape list
            _2d_array = np.array(_2d_list).reshape(
                component_no, component_no)
            # save parms matrix
            parms_matrix_list[_parms_key] = _2d_array

        # log
        # print("A_i_j: ", parms_matrix_list['A_i_j'])
        # print("B_i_j: ", parms_matrix_list['B_i_j'])

        # res
        return parms_matrix_list
    except Exception as e:
        raise Exception("Loading equation parameters failed!, ", e)

make_arg_symbols(args)

Make argument symbols

Parameters

args : dict arguments

Returns

None.

Source code in pyThermoDB/core/tablematrixequation.py

def make_arg_symbols(self, args) -> dict:
    '''
    Make argument symbols

    Parameters
    ----------
    args : dict
        arguments

    Returns
    -------
    None.
    '''
    try:
        # reset
        arg_symbols = {}

        # check
        if args is not None:
            if isinstance(args, dict):
                for key, value in args.items():
                    # symbol
                    _symbol = args[key].get('symbol')
                    # set
                    arg_symbols[_symbol] = {
                        'name': args[key].get('name'),
                        'symbol': _symbol,
                        'unit': args[key].get('unit'),
                    }

                # return
                return arg_symbols

        return {}
    except Exception as e:
        raise Exception("Making argument symbols failed!, ", e)

make_return_symbols(returns)

Make return symbols

Parameters

returns : dict returns

Returns

None.

Source code in pyThermoDB/core/tablematrixequation.py

def make_return_symbols(self, returns) -> dict:
    '''
    Make return symbols

    Parameters
    ----------
    returns : dict
        returns

    Returns
    -------
    None.
    '''
    try:
        # reset
        return_symbols = {}

        # check
        if returns is not None:
            if isinstance(returns, dict):
                for key, value in returns.items():
                    # symbol
                    _symbol = returns[key].get('symbol')
                    # set
                    return_symbols[_symbol] = {
                        'name': returns[key].get('name'),
                        'symbol': _symbol,
                        'unit': returns[key].get('unit'),
                    }

            # return
            return return_symbols

        return {}
    except Exception as e:
        raise Exception("Making return symbols failed!, ", e)

to_dict()

Convert equation to dict

Parameters

None.

Returns

res : str equation in dict

Source code in pyThermoDB/core/tablematrixequation.py

def to_dict(self):
    '''
    Convert equation to dict

    Parameters
    ----------
    None.

    Returns
    -------
    res : str
        equation in dict
    '''
    # create dict
    res = self.__prop_equation
    # yml
    # _eq_yml = _eq
    # convert to yml
    # res = yaml.dump(_eq_yml)

    return res

tablematrixdata

TableMatrixData

Source code in pyThermoDB/core/tablematrixdata.py

class TableMatrixData:
    # vars
    __trans_data = {}
    __prop_data = {}
    __matrix_symbol = None
    _table_structure = {}
    # pack
    __trans_data_pack = {}
    __prop_data_pack = {}
    # matrix elements
    __matrix_elements = None
    # matrix items
    __matrix_items: Optional[List[Dict[str, List[str | int | float]]]] = None
    # matrix item keys
    __matrix_item_keys: Optional[List[str]] = None
    # matrix mode
    matrix_mode: Literal['VALUES', 'ITEMS'] = 'VALUES'

    def __init__(
        self,
            databook_name: str | int,
            table_name: str | int,
            table_data,
            matrix_table=None,
            matrix_symbol: Optional[List[str]] = None
    ):
        # set values
        self.databook_name = databook_name
        self.table_name = table_name
        self.table_data = table_data  # NOTE: reference template (yml)
        self.matrix_table = matrix_table  # all elements saved in the matrix-table

        # NOTE: check
        if matrix_symbol is None:
            # matrix symbol such as Alpha_i_j
            symbol_ = self.table_data['MATRIX-SYMBOL']
            self.__matrix_symbol = symbol_

            # matrix items
            items_ = self.table_data.get('ITEMS', None)
            # check
            if items_ is not None and items_ != "None":
                # setting matrix items
                self.__set_matrix_items(items_)

        # NOTE: table structure
        self._table_structure = self._generate_table_structure(self.table_data)

    @property
    def trans_data_pack(self):
        return self.__trans_data_pack

    @trans_data_pack.setter
    def trans_data_pack(self, value):

        self.__trans_data_pack = {}
        self.__trans_data_pack = value

    @property
    def prop_data_pack(self):
        return self.__prop_data_pack

    @prop_data_pack.setter
    def prop_data_pack(self, value):
        self.__prop_data_pack = {}
        self.__prop_data_pack = value

    @property
    def trans_data(self):
        return self.__trans_data

    @trans_data.setter
    def trans_data(self, value):
        self.__trans_data = {}
        self.__trans_data = value

    @property
    def prop_data(self):
        return self.__prop_data

    @prop_data.setter
    def prop_data(self, value):
        self.__prop_data = {}
        exclude_key = 'matrix-data'
        self.__prop_data = {key: value for key,
                            value in value.items() if key != exclude_key}

    @property
    def matrix_symbol(self):
        return self.__matrix_symbol

    @property
    def matrix_elements(self):
        return self.__matrix_elements

    @matrix_elements.setter
    def matrix_elements(self, value):
        self.__matrix_elements = {}
        self.__matrix_elements = value

    @property
    def matrix_items(self):
        """Return matrix items if valid, otherwise None."""
        if isinstance(self.__matrix_items, list) and self.__matrix_items:
            return self.__matrix_items
        return None

    @property
    def matrix_item_keys(self):
        """Get matrix item keys"""
        return self.__matrix_item_keys

    @property
    def table_structure(self):
        """Get table structure"""
        return self._table_structure

    def __set_matrix_items(self, matrix_items):
        """Set matrix items"""
        # init
        self.__matrix_item_keys = []
        self.__matrix_items = []

        # check
        if matrix_items is not None:
            # check
            if isinstance(matrix_items, list) and len(matrix_items) > 0:

                # looping through matrix items
                for item in matrix_items:
                    # looping through item
                    for key, value in item.items():
                        # check
                        if "|" in key:
                            # split key
                            key_split = key.split('|')
                            # check
                            if len(key_split) != 2:
                                raise Exception(
                                    "Matrix item key is not in the correct format!")

                            # strip
                            key_split = [name.strip() for name in key_split]
                            # std key
                            key_std = " | ".join(key_split)

                            # NOTE: build component-n | component-n
                            keys_identical = []
                            # looping through component names
                            for name in key_split:
                                # create key
                                key_identical = f"{name.strip()} | {name.strip()}"
                                # set
                                keys_identical.append(key_identical)

                            # set
                            self.__matrix_item_keys.append(key_std)
                            self.__matrix_item_keys.extend(keys_identical)
                            # set
                            self.__matrix_items.append({
                                key_std: value
                            })

                # NOTE: update matrix mode
                if len(matrix_items) > 0:
                    self.matrix_mode = 'ITEMS'
            else:
                # set
                self.__matrix_item_keys = []
        else:
            # set
            self.__matrix_item_keys = []

    def __generate_table_items(self, component_names: list[str]):
        '''
        Generate dataframe for each matrix item

        Parameters
        ----------
        component_names : list[str]
            component names

        Notes
        -----
        The Dataframe structure is based on columns, symbols, units as:
        - header: No.,Name,Formula, matrix_symbol, matrix_symbol, ...
        - row 1: No.,Name,Formula, matrix_symbol, matrix_symbol, ...
        - row 2: None,None,None,1,1,1, ...
        - row 3: None,None,None, 1,2,1,2, ...

        Build two rows for each matrix item:
        - row 4: None, None, None, component1_name, component2_name, ...
        - row 5: None, None, None, component1_symbol, component2_symbol, ...

        Embedded the item data (List[List[str | int | float]]) in the matrix table as:
        - row 6: 1, component1_name, component1_formula, 1, 1, 1, ...
        - row 7: 2, component2_name, component2_formula, 1, 1, 1, ...
        '''
        try:
            # NOTE: matrix structure
            table_structure = self._table_structure
            # check
            if table_structure is None:
                raise Exception("Table structure is None!")

            # extract
            columns = table_structure.get('COLUMNS', None)
            symbol = table_structure.get('SYMBOL', None)
            unit = table_structure.get('UNIT', None)

            # NOTE: matrix symbols
            matrix_symbol = self.__matrix_symbol
            # number of matrix symbols
            matrix_symbol_num = len(matrix_symbol) if matrix_symbol else 0
            # check
            if matrix_symbol_num == 0:
                raise Exception("Matrix symbol is None!")

            # NOTE: item tables
            # item_tables = {}

            # SECTION: component names
            # set strip
            component_names = [name.strip() for name in component_names]
            # temp key
            key = " | ".join(component_names)

            # check
            if self.__matrix_item_keys:
                if key not in self.__matrix_item_keys:
                    return None

            # SECTION: matrix items
            # check
            if self.matrix_items and isinstance(self.matrix_items, dict):
                # selected matrix items
                value = self.matrix_items.get(key, None)

                # if value is None:
                if value is None or not isinstance(value, list) and len(value) == 0:
                    return None

                # ? key: components names [str | str]
                # ? value: components data [str | int | float]
                # key contains separator [|]
                if "|" in key:
                    # split key
                    key_split = key.split('|')
                    # check
                    if len(key_split) != 2:
                        raise Exception(
                            "Matrix item key is not in the correct format!")

                    # temp component names
                    temp_component_names_ = [
                        name.strip() for name in key_split]

                    # component idx
                    temp_comp_idx_ = [str(i+1) for i, name in enumerate(
                        temp_component_names_) if name in component_names]

                    # formula
                    temp_component_formula_ = []

                    # looping through component names
                    for name in temp_component_names_:
                        # check component values
                        for v in value:
                            # check
                            if isinstance(v, list):
                                if name in v[0:3]:
                                    # set
                                    temp_component_formula_.append(v[2])

                    # repeated based on matrix symbol
                    temp_component_names = temp_component_names_*matrix_symbol_num
                    # repeated based on matrix symbol
                    temp_component_formula = temp_component_formula_*matrix_symbol_num
                    # repeated based on matrix symbol
                    temp_component_idx = temp_comp_idx_*matrix_symbol_num

                    # NOTE: build row 3
                    row_3 = ['-', '-', '-']
                    # update row 3
                    row_3.extend(temp_component_idx)

                    # NOTE: build row 4
                    row_4 = ['None', 'None', 'None']
                    # update row 4
                    row_4.extend(temp_component_names)

                    # NOTE: build row 5
                    row_5 = ['None', 'None', 'None']
                    # update row 5
                    row_5.extend(temp_component_formula)

                    # NOTE: dataframe data
                    df_data = [
                        symbol, unit, row_3, row_4, row_5, *value
                    ]

                    # create dataframe
                    df = pd.DataFrame(
                        columns=columns,
                        data=df_data,
                    )

                    # NOTE: set
                    # item_key = " | ".join(temp_component_names_)
                    # item_tables[item_key] = df

                # res
                return df
            else:
                # res
                return None
        except Exception as e:
            raise Exception("Generating matrix items failed!, ", e)

    def _generate_table_structure(self, table_data: dict[str, Any]):
        '''
        Generate table structure from data table

        Parameters
        ----------
        table_data : dict[str, Any]
            data table
        '''
        try:
            # init
            table_structure = {}
            # looping through table data
            for key, value in self.table_data.items():
                if key != 'MATRIX-SYMBOL' and key != 'ITEMS':
                    # set
                    table_structure[key] = value

            # check
            if table_structure is None:
                raise Exception("Table structure is None!")

            # res
            return table_structure
        except Exception as e:
            raise Exception("Generating table structure failed!, ", e)

    def _find_component_prop_data(self, component_name_set: str):
        '''
        Get a component property from data table structure

        Parameters
        ----------
        component_name : str
            component name

        Returns
        -------
        value : dict
            component property
        '''
        try:
            # exclude key
            exclude_key = 'matrix-data'

            # set res
            prop_data = {}
            # looping through self.prop_data_pack
            for component_name, component_value in self.prop_data_pack.items():
                if component_name == component_name_set:
                    # check value
                    prop_data = {key: value for key,
                                 value in component_value.items() if key != exclude_key}
                    return prop_data
            # check
            if len(prop_data) == 0:
                raise Exception("Component not found!")
        except Exception as e:
            raise Exception("Finding component property failed!, ", e)

    def matrix_data_structure(self):
        '''
        Display matrix-data table structure
        '''
        try:
            # NOTE: choose from table data structure all except matrix-symbol
            # dataframe
            df = pd.DataFrame(self._table_structure)
            # add ID column
            df.insert(0, 'ID', range(1, len(df) + 1))
            # arrange columns
            # change the position of ID column to the last
            cols = df.columns.tolist()
            cols.insert(len(cols), cols.pop(cols.index('ID')))
            df = df[cols]

            return df
        except Exception as e:
            raise Exception("Matrix data structure failed!, ", e)

    def get_matrix_table(self,
                         mode: Literal[
                             'all', 'selected'
                         ] = 'all'
                         ) -> pd.DataFrame:
        '''
        Get matrix table data

        Parameters
        ----------
        mode : str
            mode of data table (all or selected)

        Returns
        -------
        pd.DataFrame
            matrix table data
        '''
        try:
            # matrix table
            matrix_table = self.matrix_table

            if matrix_table is None:
                raise Exception("Matrix table is None!")

            # NOTE: check mode
            if mode == 'all':
                # SECTION: matrix table (all data)
                return matrix_table
            elif mode == 'selected':
                # SECTION: get all records in Name column
                # matrix table
                Names = matrix_table['Name'].unique()
                Names = [str(i) for i in Names if str(i) != "-"]

                # selected records
                Names_selected = self.matrix_elements

                # check
                if Names_selected is None:
                    raise Exception("Selected records are None!")

                # reduced records
                Names_ignored = [i for i in Names if i not in Names_selected]

                # NOTE: remove row where Name is XXX
                # matrix table
                matrix_table_filtered = matrix_table[~matrix_table['Name'].isin(
                    Names_ignored)]
                # drop columns for all Names ignored
                for column in matrix_table_filtered.columns:
                    # looping through ignored names
                    for name in Names_ignored:
                        # check column name
                        if name in matrix_table_filtered[column].values:
                            # drop column
                            matrix_table_filtered = matrix_table_filtered.drop(
                                column, axis=1)
                # return filtered matrix table
                return matrix_table_filtered
            else:
                raise ValueError("Mode not recognized!")
        except Exception as e:
            raise Exception("Getting matrix table failed!, ", e)

    def get_property(self, property: str | int, component_name: str) -> DataResultType | dict:
        '''
        Get a component property from data table structure

        Parameters
        ----------
        property : str | int
            property name or id
        component_name : str
            component name

        Returns
        -------
        dict
            component property
        '''
        # find component property
        prop_data = self._find_component_prop_data(component_name)

        if not isinstance(prop_data, dict):
            raise Exception("Component property data is not a dictionary!")

        # dataframe (selected component data)
        df = pd.DataFrame(prop_data)

        # choose a column
        if isinstance(property, str):
            # df = df[property_name]
            # look up prop_data dict
            # check key exists
            if property in prop_data.keys():
                get_data = prop_data[property]  # return dict
            else:
                # check symbol value in each item
                for key, value in prop_data.items():
                    if property == value['symbol']:
                        get_data = prop_data[key]
                        break

            # print(type(get_data))
            return get_data

        elif isinstance(property, int):
            # get column index
            column_index = df.columns[property-1]
            sr: pd.Series = df.loc[:, column_index]

            # set
            get_data = sr.to_dict()

            return get_data

        else:
            raise ValueError("loading error!")

    def get_matrix_property_by_name(self, property: str) -> DataResult:
        '''
        Get a component property from data table structure

        Parameters
        ----------
        property : str
            property name or id must be string as: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol`

        Returns
        -------
        dict
            component property
        '''
        try:
            # check property name
            if "_" not in property.strip():
                raise Exception(
                    "Invalid property name. Please use the following format: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol"
                )

            # extract data
            prop_name, comp1, comp2 = property.split('_')

            # set property name
            prop_name = prop_name.strip()+'_i_j'

            # get matrix property
            matrix_property = self.get_matrix_property(
                prop_name, [comp1, comp2])

            return matrix_property
        except Exception as e:
            raise Exception("Getting matrix property failed!, ", e)

    def ij(self,
           property: str,
           symbol_format: Literal[
               'alphabetic', 'numeric'
           ] = 'alphabetic',
           message: Optional[str] = None,
           **kwargs) -> DataResult:
        '''
        Get a component property from data table structure (matrix data)

        Parameters
        ----------
        property : str
            property name or id must be string as: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol` or `Alpha | ethanol | methanol`
        symbol_format : str
            symbol format alphabetic or numeric (default: alphabetic)
        message : str
            message (default: None)
        **kwargs : dict
            additional arguments
            - mixture_name: str

        Returns
        -------
        matrix_property: DataResult
            component property taken from matrix data
        '''
        try:
            # check property name
            # check not empty
            if property is None or property.strip() == "":
                raise Exception("Property name is empty!")

            # extract data
            # NOTE: format 1: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol`
            # check contains underscore
            extracted = property.strip().split('_')

            # check len
            if len(extracted) == 3:
                prop_name, comp1, comp2 = extracted
                # remove _ij
                prop_name = prop_name.replace('_ij', '')
            else:
                # NOTE: format 2: Alpha | ethanol | methanol
                extracted = property.strip().split('|')

                # check len
                if len(extracted) == 3:
                    prop_name, comp1, comp2 = extracted
                    # remove _ij
                    prop_name = prop_name.replace('_ij', '')
                else:
                    raise Exception(
                        "Invalid property name. It should have three parts, Please use the following format: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol"
                    )

            # NOTE: check all extracted
            if prop_name is None or comp1 is None or comp2 is None:
                raise Exception("Property name is not in the correct format!")

            # trim
            prop_name = prop_name.strip()
            comp1 = comp1.strip()
            comp2 = comp2.strip()

            # set property name
            prop_name = prop_name+'_i_j'

            # set message
            if message is None:
                message = f"Get {prop_name} property from matrix data table structure"

            # NOTE: set mixture name
            # mixture name
            mixture_name = kwargs.get('mixture_name', None)
            # check
            if mixture_name is None:
                mixture_name = f"{comp1} | {comp2}"

            # get matrix property
            matrix_property = self.get_matrix_property(
                property=prop_name,
                component_names=[comp1, comp2],
                symbol_format=symbol_format,
                message=message,
                mixture_name=mixture_name)

            return matrix_property
        except Exception as e:
            raise Exception("Getting matrix property failed!, ", e)

    def get_matrix_property(
        self,
        property: str,
        component_names: list[str],
        symbol_format: Literal[
            'alphabetic', 'numeric'
        ] = 'alphabetic',
        message: str = 'Get a component property from data table structure',
        **kwargs
    ) -> DataResult:
        '''
        Get a component property from data table structure

        Parameters
        ----------
        property : str
            property must be a string as: Alpha_ij
        component_names : list[str]
            component names such as ['ethanol', 'methanol']
        symbol_format : str
            symbol format alphabetic or numeric (default: alphabetic)
        message : str
            message (default: None)
        **kwargs : dict
            additional arguments
            - mixture_name: str, mixture name

        Returns
        -------
        DataResult
            component property
        '''
        # NOTE: mixture_components
        mixture_name = kwargs.get('mixture_name', None)

        # NOTE: check matrix mode
        if self.matrix_mode == 'ITEMS':
            # SECTION: check matrix items
            # matrix_table = self.__generate_table_items(component_names)
            raise Exception(
                "Matrix items are not available! Please use the matrix table instead!")

        elif self.matrix_mode == 'VALUES':
            # SECTION: matrix structure (all data)
            matrix_table = self.matrix_table

        else:
            raise Exception("Matrix mode is not recognized!")

        # ! check dataframe
        if not isinstance(matrix_table, pd.DataFrame):
            raise Exception("Matrix data is not a dataframe!")

        # column name
        matrix_table_column_name = list(matrix_table.columns)

        # SECTION: check columns names
        # Function to normalize mixtures
        def normalize_mixture(mix):
            parts = [x.strip() for x in mix.split('|')]
            parts.sort()
            return ' | '.join(parts)

        # mixture
        if any(col.lower() == 'mixture' for col in matrix_table_column_name):
            # check
            if mixture_name is None:
                # set
                mixture_name = " | ".join(component_names)

            # sorted
            mixture_name = normalize_mixture(mixture_name)

            # build dataframe for the mixture
            # Extract header + row1 + row2
            header_rows = matrix_table.iloc[:2]  # row 0 and 1

            matrix_table['normalized_mixture'] = matrix_table['Mixture'].apply(
                normalize_mixture)

            # Filter rows where 'mixture' == specific_name
            filtered_rows = matrix_table[
                matrix_table['normalized_mixture'] == mixture_name
            ]

            # Combine into new DataFrame
            # (remove duplicates if overlap with header_rows)
            matrix_table = pd.concat(
                [header_rows, filtered_rows]
            ).drop_duplicates().reset_index(drop=True)

            # drop the normalized_mixture column
            matrix_table = matrix_table.drop(columns=['normalized_mixture'])

        # log
        # print(matrix_table)

        # SECTION: component names
        comp_i = 1
        matrix_table_component = {}
        # looping through Name column
        for i, item in enumerate(list(matrix_table['Name'])):
            # check item is a component name
            if item != "-" and len(item) > 1 and item != 'None' and item != 'None':
                matrix_table_component[item] = comp_i
                comp_i += 1

        # component names
        matrix_table_component_no = len(matrix_table_component)

        # matrix table component keys
        matrix_table_component_names = list(matrix_table_component.keys())

        # SECTION: get component data (row)
        matrix_table_comp_data = {}
        # looping through component
        for i in range(matrix_table_component_no):
            # define filter for component
            component_name_filter = matrix_table_component_names[i]

            # get component data
            _data_get = matrix_table[matrix_table['Name'].str.match(
                component_name_filter, case=False, na=False)]

            # set
            _row_index = int(_data_get.index[0])
            _data = _data_get.to_dict(orient='records')[0]

            # update
            _data['row_index'] = _row_index

            # check
            if len(_data) == 0:
                raise Exception("No data for component: " +
                                component_name_filter)

            # get component data
            _component_name = _data['Name']
            matrix_table_comp_data[_component_name] = _data

        # SECTION: manage property
        if isinstance(property, str) and property.endswith('_i_j'):
            # find the columns
            _property = property.split('_')
            property_name = _property[0]

            # matrix columns
            matrix_columns = []
            # matrix column index
            matrix_column_index = []

            # look for the property name in the column names
            for column in matrix_table_column_name:
                # column name set
                column_set = column.split('_')[0]
                # check
                if property_name.upper() == column_set.upper():
                    # get the column index
                    column_index = matrix_table_column_name.index(column)
                    # get the column
                    matrix_columns.append(column)
                    # get the column index
                    matrix_column_index.append(column_index)

            # check matrix columns
            if len(matrix_columns) != matrix_table_component_no:
                raise Exception(
                    "Matrix columns do not match the number of components!")
            # check matrix column index
            if len(matrix_column_index) != matrix_table_component_no:
                raise Exception(
                    "Matrix column index does not match the number of components!")

            # property value
            comp1_index = matrix_table_component[component_names[0]] - 1
            comp2_index = matrix_table_component[component_names[1]] - 1

            # row index component 1
            row_index_comp1 = matrix_table_comp_data[component_names[0]].get(
                'row_index')
            # row index component 2
            row_index_comp2 = matrix_table_comp_data[component_names[1]].get(
                'row_index')

            # property column
            property_column = matrix_columns[comp2_index]
            # get index
            property_column_index = matrix_column_index[comp2_index]

            # get property value
            property_value = matrix_table.iat[row_index_comp1,
                                              property_column_index]

            # get property symbol
            symbol_idx = str(matrix_table.iloc[0, property_column_index]).split('_')[
                0]+'_'+str(comp1_index+1)+'_'+str(comp2_index+1)
            # symbol name
            symbol_name = str(matrix_table.iloc[0, property_column_index]).split('_')[
                0]+'_'+str(component_names[0])+'_'+str(component_names[1])

            # set symbol
            if symbol_format.lower() == 'alphabetic':
                property_symbol = symbol_name
            elif symbol_format.lower() == 'numeric':
                property_symbol = symbol_idx
            else:
                raise ValueError(
                    f"Symbol format {symbol_format} not recognized.")

            # get property unit
            property_unit = matrix_table.iloc[1, property_column_index]

            # res
            res: DataResult = {
                "property_name": str(property_name),
                "symbol": str(property_symbol),
                "unit": str(property_unit),
                "value": float(property_value),
                "message": message if message else "No message",
                "databook_name": self.databook_name,
                "table_name": self.table_name
            }

            # return
            return res
        else:
            raise ValueError(f"Property format {property} not recognized.")

    def ijs(self,
            property: str,
            res_format: Literal[
                'alphabetic', 'numeric'
            ] = 'alphabetic',
            symbol_delimiter: Literal[
                "|", "_"
            ] = "|"
            ) -> Dict[str, float | int] | np.ndarray:
        '''
        Generate a dictionary for ij property

        Parameters
        ----------
        property : str
            property name must be string as: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol` or `Alpha | ethanol | methanol`
        res_format : str
            result format (default: dict)
        symbol_delimiter : str
            symbol delimiter (default: |), array element symbol delimiter
            such as `Alpha | ethanol | methanol` or `Alpha_ethanol_methanol`

        Returns
        -------
        dict
            dictionary for ij property
        '''
        try:
            # check property name
            # check not empty
            if property is None or property.strip() == "":
                raise Exception("Property name is empty!")

            # extract data
            # NOTE: format 1: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol`
            # check contains underscore
            extracted = property.strip().split('_')

            # check len
            if len(extracted) == 3:
                prop_name, comp1, comp2 = extracted
                # remove _ij
                prop_name = prop_name.replace('_ij', '')
            else:
                # NOTE: format 2: Alpha | ethanol | methanol
                extracted = property.strip().split('|')

                # check len
                if len(extracted) == 3:
                    prop_name, comp1, comp2 = extracted
                    # remove _ij
                    prop_name = prop_name.replace('_ij', '')
                else:
                    raise Exception(
                        "Invalid property name. It should have three parts, Please use the following format: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol"
                    )

            # NOTE: check all extracted
            if prop_name is None or comp1 is None or comp2 is None:
                raise Exception("Property name is not in the correct format!")

            # check
            if comp1 == comp2:
                raise Exception("Component names are the same!")

            # set property name
            prop_name = prop_name.strip()

            # components
            components = [comp1.strip(), comp2.strip()]

            # res
            res_array = np.zeros((len(components), len(components)))
            res_dict = {}

            # NOTE: set
            if symbol_delimiter == "_":
                symbol_delimiter_set = "_"
            elif symbol_delimiter == "|":
                symbol_delimiter_set = " | "
            else:
                raise Exception("Symbol delimiter not recognized!")

            # NOTE: define mixture
            # mixture name
            mixture_name = f"{components[0]} | {components[1]}"

            # NOTE: extract data
            for i in range(len(components)):
                for j in range(len(components)):
                    # key
                    key = f"{components[i]}_{components[j]}"
                    prop_ = f"{prop_name}_{key}"

                    # get property
                    val = self.ij(
                        prop_,
                        mixture_name=mixture_name).get('value')

                    # set
                    key_comp = f"{components[i]}{symbol_delimiter_set}{components[j]}"
                    res_dict[key_comp] = val
                    res_array[i][j] = val

            # check
            if res_format == 'alphabetic':
                # NOTE: convert to alphabetic format
                return res_dict
            elif res_format == 'numeric':
                # NOTE: convert to numeric format
                return res_array
            else:
                raise Exception("Result format not recognized!")

        except Exception as e:
            raise Exception("Generating dictionary failed!, ", e)

    def mat(self,
            property_name: str,
            component_names: list[str],
            symbol_format: Literal[
                'alphabetic', 'numeric'
            ] = 'numeric'
            ) -> Dict[str, str | float | int] | np.ndarray:
        '''
        Get matrix data

        Parameters
        ----------
        property_name : str
            property name such as `Alpha` represented `Alpha_ij`
        component_names : list[str]
            component names such as ['ethanol', 'methanol']
        symbol_format : str
            symbol format alphabetic or numeric (default: numeric)

        Returns
        -------
        dict | np.ndarray
            matrix data (dict or np.ndarray)
        '''
        try:
            # NOTE: check property name
            # check not empty
            if property_name is None or property_name.strip() == "":
                raise Exception("Property name is empty!")
            # set
            property_name = property_name.strip()
            # remove _i_j
            property_name = property_name.replace('_i_j', '')

            # NOTE: check component names
            if component_names is None or len(component_names) == 0:
                raise Exception("Component names are empty!")
            # component num
            component_num = len(component_names)

            # component strip
            components = [name.strip() for name in component_names]

            # NOTE: matrix data
            mat_ij = np.zeros((component_num, component_num))

            # matrix data dict
            mat_ij_dict: Dict[str, str | float | int] = {}

            # NOTE: mixture name
            mixture_name = f"{components[0]} | {components[1]}"

            # looping through component names
            for i in range(component_num):
                for j in range(component_num):
                    # key
                    key = f"{components[i]}_{components[j]}"
                    prop_ = f"{property_name}_{key}"
                    # get matrix property
                    matrix_property = self.ij(
                        prop_,
                        mixture_name=mixture_name
                    )

                    # set value
                    mat_ij[i][j] = matrix_property['value']

                    # set dict
                    key_dict = f"{components[i]} | {components[j]}"
                    # ? return 0 if value is None
                    mat_ij_dict[key_dict] = matrix_property['value'] or 0

            # check
            if mat_ij is None:
                raise Exception("Matrix data is None!")

            # return
            if symbol_format == 'alphabetic':
                return mat_ij_dict
            elif symbol_format == 'numeric':
                return mat_ij
            else:
                raise Exception("Symbol format not recognized!")
        except Exception as e:
            raise Exception("Getting matrix data failed!, ", e)

    def to_dict(self):
        '''
        Convert prop to dict

        Parameters
        ----------
        component_name : str
            component name

        Returns
        -------
        res : dict
            dict
        '''
        try:
            # comp data
            res = self.prop_data

            return res
        except Exception as e:
            raise Exception("Conversion failed!, ", e)

matrix_item_keys property

Get matrix item keys

matrix_items property

Return matrix items if valid, otherwise None.

table_structure property

Get table structure

__generate_table_items(component_names)

Generate dataframe for each matrix item

Parameters

component_names : list[str] component names

Notes

The Dataframe structure is based on columns, symbols, units as: - header: No.,Name,Formula, matrix_symbol, matrix_symbol, ... - row 1: No.,Name,Formula, matrix_symbol, matrix_symbol, ... - row 2: None,None,None,1,1,1, ... - row 3: None,None,None, 1,2,1,2, ...

Build two rows for each matrix item: - row 4: None, None, None, component1_name, component2_name, ... - row 5: None, None, None, component1_symbol, component2_symbol, ...

Embedded the item data (List[List[str | int | float]]) in the matrix table as: - row 6: 1, component1_name, component1_formula, 1, 1, 1, ... - row 7: 2, component2_name, component2_formula, 1, 1, 1, ...

Source code in pyThermoDB/core/tablematrixdata.py

def __generate_table_items(self, component_names: list[str]):
    '''
    Generate dataframe for each matrix item

    Parameters
    ----------
    component_names : list[str]
        component names

    Notes
    -----
    The Dataframe structure is based on columns, symbols, units as:
    - header: No.,Name,Formula, matrix_symbol, matrix_symbol, ...
    - row 1: No.,Name,Formula, matrix_symbol, matrix_symbol, ...
    - row 2: None,None,None,1,1,1, ...
    - row 3: None,None,None, 1,2,1,2, ...

    Build two rows for each matrix item:
    - row 4: None, None, None, component1_name, component2_name, ...
    - row 5: None, None, None, component1_symbol, component2_symbol, ...

    Embedded the item data (List[List[str | int | float]]) in the matrix table as:
    - row 6: 1, component1_name, component1_formula, 1, 1, 1, ...
    - row 7: 2, component2_name, component2_formula, 1, 1, 1, ...
    '''
    try:
        # NOTE: matrix structure
        table_structure = self._table_structure
        # check
        if table_structure is None:
            raise Exception("Table structure is None!")

        # extract
        columns = table_structure.get('COLUMNS', None)
        symbol = table_structure.get('SYMBOL', None)
        unit = table_structure.get('UNIT', None)

        # NOTE: matrix symbols
        matrix_symbol = self.__matrix_symbol
        # number of matrix symbols
        matrix_symbol_num = len(matrix_symbol) if matrix_symbol else 0
        # check
        if matrix_symbol_num == 0:
            raise Exception("Matrix symbol is None!")

        # NOTE: item tables
        # item_tables = {}

        # SECTION: component names
        # set strip
        component_names = [name.strip() for name in component_names]
        # temp key
        key = " | ".join(component_names)

        # check
        if self.__matrix_item_keys:
            if key not in self.__matrix_item_keys:
                return None

        # SECTION: matrix items
        # check
        if self.matrix_items and isinstance(self.matrix_items, dict):
            # selected matrix items
            value = self.matrix_items.get(key, None)

            # if value is None:
            if value is None or not isinstance(value, list) and len(value) == 0:
                return None

            # ? key: components names [str | str]
            # ? value: components data [str | int | float]
            # key contains separator [|]
            if "|" in key:
                # split key
                key_split = key.split('|')
                # check
                if len(key_split) != 2:
                    raise Exception(
                        "Matrix item key is not in the correct format!")

                # temp component names
                temp_component_names_ = [
                    name.strip() for name in key_split]

                # component idx
                temp_comp_idx_ = [str(i+1) for i, name in enumerate(
                    temp_component_names_) if name in component_names]

                # formula
                temp_component_formula_ = []

                # looping through component names
                for name in temp_component_names_:
                    # check component values
                    for v in value:
                        # check
                        if isinstance(v, list):
                            if name in v[0:3]:
                                # set
                                temp_component_formula_.append(v[2])

                # repeated based on matrix symbol
                temp_component_names = temp_component_names_*matrix_symbol_num
                # repeated based on matrix symbol
                temp_component_formula = temp_component_formula_*matrix_symbol_num
                # repeated based on matrix symbol
                temp_component_idx = temp_comp_idx_*matrix_symbol_num

                # NOTE: build row 3
                row_3 = ['-', '-', '-']
                # update row 3
                row_3.extend(temp_component_idx)

                # NOTE: build row 4
                row_4 = ['None', 'None', 'None']
                # update row 4
                row_4.extend(temp_component_names)

                # NOTE: build row 5
                row_5 = ['None', 'None', 'None']
                # update row 5
                row_5.extend(temp_component_formula)

                # NOTE: dataframe data
                df_data = [
                    symbol, unit, row_3, row_4, row_5, *value
                ]

                # create dataframe
                df = pd.DataFrame(
                    columns=columns,
                    data=df_data,
                )

                # NOTE: set
                # item_key = " | ".join(temp_component_names_)
                # item_tables[item_key] = df

            # res
            return df
        else:
            # res
            return None
    except Exception as e:
        raise Exception("Generating matrix items failed!, ", e)

__set_matrix_items(matrix_items)

Set matrix items

Source code in pyThermoDB/core/tablematrixdata.py

def __set_matrix_items(self, matrix_items):
    """Set matrix items"""
    # init
    self.__matrix_item_keys = []
    self.__matrix_items = []

    # check
    if matrix_items is not None:
        # check
        if isinstance(matrix_items, list) and len(matrix_items) > 0:

            # looping through matrix items
            for item in matrix_items:
                # looping through item
                for key, value in item.items():
                    # check
                    if "|" in key:
                        # split key
                        key_split = key.split('|')
                        # check
                        if len(key_split) != 2:
                            raise Exception(
                                "Matrix item key is not in the correct format!")

                        # strip
                        key_split = [name.strip() for name in key_split]
                        # std key
                        key_std = " | ".join(key_split)

                        # NOTE: build component-n | component-n
                        keys_identical = []
                        # looping through component names
                        for name in key_split:
                            # create key
                            key_identical = f"{name.strip()} | {name.strip()}"
                            # set
                            keys_identical.append(key_identical)

                        # set
                        self.__matrix_item_keys.append(key_std)
                        self.__matrix_item_keys.extend(keys_identical)
                        # set
                        self.__matrix_items.append({
                            key_std: value
                        })

            # NOTE: update matrix mode
            if len(matrix_items) > 0:
                self.matrix_mode = 'ITEMS'
        else:
            # set
            self.__matrix_item_keys = []
    else:
        # set
        self.__matrix_item_keys = []

get_matrix_property(property, component_names, symbol_format='alphabetic', message='Get a component property from data table structure', **kwargs)

Get a component property from data table structure

Parameters

property : str property must be a string as: Alpha_ij component_names : list[str] component names such as ['ethanol', 'methanol'] symbol_format : str symbol format alphabetic or numeric (default: alphabetic) message : str message (default: None) **kwargs : dict additional arguments - mixture_name: str, mixture name

Returns

DataResult component property

Source code in pyThermoDB/core/tablematrixdata.py

def get_matrix_property(
    self,
    property: str,
    component_names: list[str],
    symbol_format: Literal[
        'alphabetic', 'numeric'
    ] = 'alphabetic',
    message: str = 'Get a component property from data table structure',
    **kwargs
) -> DataResult:
    '''
    Get a component property from data table structure

    Parameters
    ----------
    property : str
        property must be a string as: Alpha_ij
    component_names : list[str]
        component names such as ['ethanol', 'methanol']
    symbol_format : str
        symbol format alphabetic or numeric (default: alphabetic)
    message : str
        message (default: None)
    **kwargs : dict
        additional arguments
        - mixture_name: str, mixture name

    Returns
    -------
    DataResult
        component property
    '''
    # NOTE: mixture_components
    mixture_name = kwargs.get('mixture_name', None)

    # NOTE: check matrix mode
    if self.matrix_mode == 'ITEMS':
        # SECTION: check matrix items
        # matrix_table = self.__generate_table_items(component_names)
        raise Exception(
            "Matrix items are not available! Please use the matrix table instead!")

    elif self.matrix_mode == 'VALUES':
        # SECTION: matrix structure (all data)
        matrix_table = self.matrix_table

    else:
        raise Exception("Matrix mode is not recognized!")

    # ! check dataframe
    if not isinstance(matrix_table, pd.DataFrame):
        raise Exception("Matrix data is not a dataframe!")

    # column name
    matrix_table_column_name = list(matrix_table.columns)

    # SECTION: check columns names
    # Function to normalize mixtures
    def normalize_mixture(mix):
        parts = [x.strip() for x in mix.split('|')]
        parts.sort()
        return ' | '.join(parts)

    # mixture
    if any(col.lower() == 'mixture' for col in matrix_table_column_name):
        # check
        if mixture_name is None:
            # set
            mixture_name = " | ".join(component_names)

        # sorted
        mixture_name = normalize_mixture(mixture_name)

        # build dataframe for the mixture
        # Extract header + row1 + row2
        header_rows = matrix_table.iloc[:2]  # row 0 and 1

        matrix_table['normalized_mixture'] = matrix_table['Mixture'].apply(
            normalize_mixture)

        # Filter rows where 'mixture' == specific_name
        filtered_rows = matrix_table[
            matrix_table['normalized_mixture'] == mixture_name
        ]

        # Combine into new DataFrame
        # (remove duplicates if overlap with header_rows)
        matrix_table = pd.concat(
            [header_rows, filtered_rows]
        ).drop_duplicates().reset_index(drop=True)

        # drop the normalized_mixture column
        matrix_table = matrix_table.drop(columns=['normalized_mixture'])

    # log
    # print(matrix_table)

    # SECTION: component names
    comp_i = 1
    matrix_table_component = {}
    # looping through Name column
    for i, item in enumerate(list(matrix_table['Name'])):
        # check item is a component name
        if item != "-" and len(item) > 1 and item != 'None' and item != 'None':
            matrix_table_component[item] = comp_i
            comp_i += 1

    # component names
    matrix_table_component_no = len(matrix_table_component)

    # matrix table component keys
    matrix_table_component_names = list(matrix_table_component.keys())

    # SECTION: get component data (row)
    matrix_table_comp_data = {}
    # looping through component
    for i in range(matrix_table_component_no):
        # define filter for component
        component_name_filter = matrix_table_component_names[i]

        # get component data
        _data_get = matrix_table[matrix_table['Name'].str.match(
            component_name_filter, case=False, na=False)]

        # set
        _row_index = int(_data_get.index[0])
        _data = _data_get.to_dict(orient='records')[0]

        # update
        _data['row_index'] = _row_index

        # check
        if len(_data) == 0:
            raise Exception("No data for component: " +
                            component_name_filter)

        # get component data
        _component_name = _data['Name']
        matrix_table_comp_data[_component_name] = _data

    # SECTION: manage property
    if isinstance(property, str) and property.endswith('_i_j'):
        # find the columns
        _property = property.split('_')
        property_name = _property[0]

        # matrix columns
        matrix_columns = []
        # matrix column index
        matrix_column_index = []

        # look for the property name in the column names
        for column in matrix_table_column_name:
            # column name set
            column_set = column.split('_')[0]
            # check
            if property_name.upper() == column_set.upper():
                # get the column index
                column_index = matrix_table_column_name.index(column)
                # get the column
                matrix_columns.append(column)
                # get the column index
                matrix_column_index.append(column_index)

        # check matrix columns
        if len(matrix_columns) != matrix_table_component_no:
            raise Exception(
                "Matrix columns do not match the number of components!")
        # check matrix column index
        if len(matrix_column_index) != matrix_table_component_no:
            raise Exception(
                "Matrix column index does not match the number of components!")

        # property value
        comp1_index = matrix_table_component[component_names[0]] - 1
        comp2_index = matrix_table_component[component_names[1]] - 1

        # row index component 1
        row_index_comp1 = matrix_table_comp_data[component_names[0]].get(
            'row_index')
        # row index component 2
        row_index_comp2 = matrix_table_comp_data[component_names[1]].get(
            'row_index')

        # property column
        property_column = matrix_columns[comp2_index]
        # get index
        property_column_index = matrix_column_index[comp2_index]

        # get property value
        property_value = matrix_table.iat[row_index_comp1,
                                          property_column_index]

        # get property symbol
        symbol_idx = str(matrix_table.iloc[0, property_column_index]).split('_')[
            0]+'_'+str(comp1_index+1)+'_'+str(comp2_index+1)
        # symbol name
        symbol_name = str(matrix_table.iloc[0, property_column_index]).split('_')[
            0]+'_'+str(component_names[0])+'_'+str(component_names[1])

        # set symbol
        if symbol_format.lower() == 'alphabetic':
            property_symbol = symbol_name
        elif symbol_format.lower() == 'numeric':
            property_symbol = symbol_idx
        else:
            raise ValueError(
                f"Symbol format {symbol_format} not recognized.")

        # get property unit
        property_unit = matrix_table.iloc[1, property_column_index]

        # res
        res: DataResult = {
            "property_name": str(property_name),
            "symbol": str(property_symbol),
            "unit": str(property_unit),
            "value": float(property_value),
            "message": message if message else "No message",
            "databook_name": self.databook_name,
            "table_name": self.table_name
        }

        # return
        return res
    else:
        raise ValueError(f"Property format {property} not recognized.")

get_matrix_property_by_name(property)

Get a component property from data table structure

Parameters

property : str property name or id must be string as: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol

Returns

dict component property

Source code in pyThermoDB/core/tablematrixdata.py

def get_matrix_property_by_name(self, property: str) -> DataResult:
    '''
    Get a component property from data table structure

    Parameters
    ----------
    property : str
        property name or id must be string as: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol`

    Returns
    -------
    dict
        component property
    '''
    try:
        # check property name
        if "_" not in property.strip():
            raise Exception(
                "Invalid property name. Please use the following format: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol"
            )

        # extract data
        prop_name, comp1, comp2 = property.split('_')

        # set property name
        prop_name = prop_name.strip()+'_i_j'

        # get matrix property
        matrix_property = self.get_matrix_property(
            prop_name, [comp1, comp2])

        return matrix_property
    except Exception as e:
        raise Exception("Getting matrix property failed!, ", e)

get_matrix_table(mode='all')

Get matrix table data

Parameters

mode : str mode of data table (all or selected)

Returns

pd.DataFrame matrix table data

Source code in pyThermoDB/core/tablematrixdata.py

def get_matrix_table(self,
                     mode: Literal[
                         'all', 'selected'
                     ] = 'all'
                     ) -> pd.DataFrame:
    '''
    Get matrix table data

    Parameters
    ----------
    mode : str
        mode of data table (all or selected)

    Returns
    -------
    pd.DataFrame
        matrix table data
    '''
    try:
        # matrix table
        matrix_table = self.matrix_table

        if matrix_table is None:
            raise Exception("Matrix table is None!")

        # NOTE: check mode
        if mode == 'all':
            # SECTION: matrix table (all data)
            return matrix_table
        elif mode == 'selected':
            # SECTION: get all records in Name column
            # matrix table
            Names = matrix_table['Name'].unique()
            Names = [str(i) for i in Names if str(i) != "-"]

            # selected records
            Names_selected = self.matrix_elements

            # check
            if Names_selected is None:
                raise Exception("Selected records are None!")

            # reduced records
            Names_ignored = [i for i in Names if i not in Names_selected]

            # NOTE: remove row where Name is XXX
            # matrix table
            matrix_table_filtered = matrix_table[~matrix_table['Name'].isin(
                Names_ignored)]
            # drop columns for all Names ignored
            for column in matrix_table_filtered.columns:
                # looping through ignored names
                for name in Names_ignored:
                    # check column name
                    if name in matrix_table_filtered[column].values:
                        # drop column
                        matrix_table_filtered = matrix_table_filtered.drop(
                            column, axis=1)
            # return filtered matrix table
            return matrix_table_filtered
        else:
            raise ValueError("Mode not recognized!")
    except Exception as e:
        raise Exception("Getting matrix table failed!, ", e)

get_property(property, component_name)

Get a component property from data table structure

Parameters

property : str | int property name or id component_name : str component name

Returns

dict component property

Source code in pyThermoDB/core/tablematrixdata.py

def get_property(self, property: str | int, component_name: str) -> DataResultType | dict:
    '''
    Get a component property from data table structure

    Parameters
    ----------
    property : str | int
        property name or id
    component_name : str
        component name

    Returns
    -------
    dict
        component property
    '''
    # find component property
    prop_data = self._find_component_prop_data(component_name)

    if not isinstance(prop_data, dict):
        raise Exception("Component property data is not a dictionary!")

    # dataframe (selected component data)
    df = pd.DataFrame(prop_data)

    # choose a column
    if isinstance(property, str):
        # df = df[property_name]
        # look up prop_data dict
        # check key exists
        if property in prop_data.keys():
            get_data = prop_data[property]  # return dict
        else:
            # check symbol value in each item
            for key, value in prop_data.items():
                if property == value['symbol']:
                    get_data = prop_data[key]
                    break

        # print(type(get_data))
        return get_data

    elif isinstance(property, int):
        # get column index
        column_index = df.columns[property-1]
        sr: pd.Series = df.loc[:, column_index]

        # set
        get_data = sr.to_dict()

        return get_data

    else:
        raise ValueError("loading error!")

ij(property, symbol_format='alphabetic', message=None, **kwargs)

Get a component property from data table structure (matrix data)

Parameters

property : str property name or id must be string as: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol or Alpha | ethanol | methanol symbol_format : str symbol format alphabetic or numeric (default: alphabetic) message : str message (default: None) **kwargs : dict additional arguments - mixture_name: str

Returns

matrix_property: DataResult component property taken from matrix data

Source code in pyThermoDB/core/tablematrixdata.py

def ij(self,
       property: str,
       symbol_format: Literal[
           'alphabetic', 'numeric'
       ] = 'alphabetic',
       message: Optional[str] = None,
       **kwargs) -> DataResult:
    '''
    Get a component property from data table structure (matrix data)

    Parameters
    ----------
    property : str
        property name or id must be string as: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol` or `Alpha | ethanol | methanol`
    symbol_format : str
        symbol format alphabetic or numeric (default: alphabetic)
    message : str
        message (default: None)
    **kwargs : dict
        additional arguments
        - mixture_name: str

    Returns
    -------
    matrix_property: DataResult
        component property taken from matrix data
    '''
    try:
        # check property name
        # check not empty
        if property is None or property.strip() == "":
            raise Exception("Property name is empty!")

        # extract data
        # NOTE: format 1: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol`
        # check contains underscore
        extracted = property.strip().split('_')

        # check len
        if len(extracted) == 3:
            prop_name, comp1, comp2 = extracted
            # remove _ij
            prop_name = prop_name.replace('_ij', '')
        else:
            # NOTE: format 2: Alpha | ethanol | methanol
            extracted = property.strip().split('|')

            # check len
            if len(extracted) == 3:
                prop_name, comp1, comp2 = extracted
                # remove _ij
                prop_name = prop_name.replace('_ij', '')
            else:
                raise Exception(
                    "Invalid property name. It should have three parts, Please use the following format: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol"
                )

        # NOTE: check all extracted
        if prop_name is None or comp1 is None or comp2 is None:
            raise Exception("Property name is not in the correct format!")

        # trim
        prop_name = prop_name.strip()
        comp1 = comp1.strip()
        comp2 = comp2.strip()

        # set property name
        prop_name = prop_name+'_i_j'

        # set message
        if message is None:
            message = f"Get {prop_name} property from matrix data table structure"

        # NOTE: set mixture name
        # mixture name
        mixture_name = kwargs.get('mixture_name', None)
        # check
        if mixture_name is None:
            mixture_name = f"{comp1} | {comp2}"

        # get matrix property
        matrix_property = self.get_matrix_property(
            property=prop_name,
            component_names=[comp1, comp2],
            symbol_format=symbol_format,
            message=message,
            mixture_name=mixture_name)

        return matrix_property
    except Exception as e:
        raise Exception("Getting matrix property failed!, ", e)

ijs(property, res_format='alphabetic', symbol_delimiter='|')

Generate a dictionary for ij property

Parameters

property : str property name must be string as: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol or Alpha | ethanol | methanol res_format : str result format (default: dict) symbol_delimiter : str symbol delimiter (default: |), array element symbol delimiter such as Alpha | ethanol | methanol or Alpha_ethanol_methanol

Returns

dict dictionary for ij property

Source code in pyThermoDB/core/tablematrixdata.py

def ijs(self,
        property: str,
        res_format: Literal[
            'alphabetic', 'numeric'
        ] = 'alphabetic',
        symbol_delimiter: Literal[
            "|", "_"
        ] = "|"
        ) -> Dict[str, float | int] | np.ndarray:
    '''
    Generate a dictionary for ij property

    Parameters
    ----------
    property : str
        property name must be string as: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol` or `Alpha | ethanol | methanol`
    res_format : str
        result format (default: dict)
    symbol_delimiter : str
        symbol delimiter (default: |), array element symbol delimiter
        such as `Alpha | ethanol | methanol` or `Alpha_ethanol_methanol`

    Returns
    -------
    dict
        dictionary for ij property
    '''
    try:
        # check property name
        # check not empty
        if property is None or property.strip() == "":
            raise Exception("Property name is empty!")

        # extract data
        # NOTE: format 1: Alpha_ij (i,j are component names) such as `Alpha_ethanol_methanol`
        # check contains underscore
        extracted = property.strip().split('_')

        # check len
        if len(extracted) == 3:
            prop_name, comp1, comp2 = extracted
            # remove _ij
            prop_name = prop_name.replace('_ij', '')
        else:
            # NOTE: format 2: Alpha | ethanol | methanol
            extracted = property.strip().split('|')

            # check len
            if len(extracted) == 3:
                prop_name, comp1, comp2 = extracted
                # remove _ij
                prop_name = prop_name.replace('_ij', '')
            else:
                raise Exception(
                    "Invalid property name. It should have three parts, Please use the following format: Alpha_ij (i,j are component names) such as Alpha_ethanol_methanol"
                )

        # NOTE: check all extracted
        if prop_name is None or comp1 is None or comp2 is None:
            raise Exception("Property name is not in the correct format!")

        # check
        if comp1 == comp2:
            raise Exception("Component names are the same!")

        # set property name
        prop_name = prop_name.strip()

        # components
        components = [comp1.strip(), comp2.strip()]

        # res
        res_array = np.zeros((len(components), len(components)))
        res_dict = {}

        # NOTE: set
        if symbol_delimiter == "_":
            symbol_delimiter_set = "_"
        elif symbol_delimiter == "|":
            symbol_delimiter_set = " | "
        else:
            raise Exception("Symbol delimiter not recognized!")

        # NOTE: define mixture
        # mixture name
        mixture_name = f"{components[0]} | {components[1]}"

        # NOTE: extract data
        for i in range(len(components)):
            for j in range(len(components)):
                # key
                key = f"{components[i]}_{components[j]}"
                prop_ = f"{prop_name}_{key}"

                # get property
                val = self.ij(
                    prop_,
                    mixture_name=mixture_name).get('value')

                # set
                key_comp = f"{components[i]}{symbol_delimiter_set}{components[j]}"
                res_dict[key_comp] = val
                res_array[i][j] = val

        # check
        if res_format == 'alphabetic':
            # NOTE: convert to alphabetic format
            return res_dict
        elif res_format == 'numeric':
            # NOTE: convert to numeric format
            return res_array
        else:
            raise Exception("Result format not recognized!")

    except Exception as e:
        raise Exception("Generating dictionary failed!, ", e)

mat(property_name, component_names, symbol_format='numeric')

Get matrix data

Parameters

property_name : str property name such as Alpha represented Alpha_ij component_names : list[str] component names such as ['ethanol', 'methanol'] symbol_format : str symbol format alphabetic or numeric (default: numeric)

Returns

dict | np.ndarray matrix data (dict or np.ndarray)

Source code in pyThermoDB/core/tablematrixdata.py

def mat(self,
        property_name: str,
        component_names: list[str],
        symbol_format: Literal[
            'alphabetic', 'numeric'
        ] = 'numeric'
        ) -> Dict[str, str | float | int] | np.ndarray:
    '''
    Get matrix data

    Parameters
    ----------
    property_name : str
        property name such as `Alpha` represented `Alpha_ij`
    component_names : list[str]
        component names such as ['ethanol', 'methanol']
    symbol_format : str
        symbol format alphabetic or numeric (default: numeric)

    Returns
    -------
    dict | np.ndarray
        matrix data (dict or np.ndarray)
    '''
    try:
        # NOTE: check property name
        # check not empty
        if property_name is None or property_name.strip() == "":
            raise Exception("Property name is empty!")
        # set
        property_name = property_name.strip()
        # remove _i_j
        property_name = property_name.replace('_i_j', '')

        # NOTE: check component names
        if component_names is None or len(component_names) == 0:
            raise Exception("Component names are empty!")
        # component num
        component_num = len(component_names)

        # component strip
        components = [name.strip() for name in component_names]

        # NOTE: matrix data
        mat_ij = np.zeros((component_num, component_num))

        # matrix data dict
        mat_ij_dict: Dict[str, str | float | int] = {}

        # NOTE: mixture name
        mixture_name = f"{components[0]} | {components[1]}"

        # looping through component names
        for i in range(component_num):
            for j in range(component_num):
                # key
                key = f"{components[i]}_{components[j]}"
                prop_ = f"{property_name}_{key}"
                # get matrix property
                matrix_property = self.ij(
                    prop_,
                    mixture_name=mixture_name
                )

                # set value
                mat_ij[i][j] = matrix_property['value']

                # set dict
                key_dict = f"{components[i]} | {components[j]}"
                # ? return 0 if value is None
                mat_ij_dict[key_dict] = matrix_property['value'] or 0

        # check
        if mat_ij is None:
            raise Exception("Matrix data is None!")

        # return
        if symbol_format == 'alphabetic':
            return mat_ij_dict
        elif symbol_format == 'numeric':
            return mat_ij
        else:
            raise Exception("Symbol format not recognized!")
    except Exception as e:
        raise Exception("Getting matrix data failed!, ", e)

matrix_data_structure()

Display matrix-data table structure

Source code in pyThermoDB/core/tablematrixdata.py

def matrix_data_structure(self):
    '''
    Display matrix-data table structure
    '''
    try:
        # NOTE: choose from table data structure all except matrix-symbol
        # dataframe
        df = pd.DataFrame(self._table_structure)
        # add ID column
        df.insert(0, 'ID', range(1, len(df) + 1))
        # arrange columns
        # change the position of ID column to the last
        cols = df.columns.tolist()
        cols.insert(len(cols), cols.pop(cols.index('ID')))
        df = df[cols]

        return df
    except Exception as e:
        raise Exception("Matrix data structure failed!, ", e)

to_dict()

Convert prop to dict

Parameters

component_name : str component name

Returns

res : dict dict

Source code in pyThermoDB/core/tablematrixdata.py

def to_dict(self):
    '''
    Convert prop to dict

    Parameters
    ----------
    component_name : str
        component name

    Returns
    -------
    res : dict
        dict
    '''
    try:
        # comp data
        res = self.prop_data

        return res
    except Exception as e:
        raise Exception("Conversion failed!, ", e)

managedata

ManageData

Source code in pyThermoDB/manager/managedata.py

class ManageData():
    # main data
    __reference = {}
    # reference local
    __reference_local_no = 0
    # databook bulk
    __databook_bulk = {}
    # databook
    __databook = []
    # databook local
    __databook_local = []
    # table
    __tables = []
    # symbol list
    __symbols = {}
    # description
    __description = {}

    def __init__(
            self,
            custom_ref: Optional[CustomRef] = None
    ):
        # external reference
        self.custom_ref = custom_ref
        # load reference
        self.__reference = self.load_reference(custom_ref)

        # symbols
        self.__symbols = self.load_symbols(custom_ref)

        # description
        self.__description = self.load_descriptions()

        # databook bulk
        self.__databook_bulk = self.get_databook_bulk()

        # databook
        self.__databook = list(self.__databook_bulk.keys())

    @property
    def reference(self):
        return self.__reference

    @property
    def reference_local_no(self):
        return self.__reference_local_no

    @reference_local_no.setter
    def reference_local_no(self, value):
        self.__reference_local_no = value

    @property
    def symbols(self):
        return self.__symbols

    @property
    def databook(self):
        return self.__databook

    @databook.setter
    def databook(self, value):
        self.__databook = []
        self.__databook = value

    @property
    def databook_bulk(self):
        return self.__databook_bulk

    @databook_bulk.setter
    def databook_bulk(self, value):
        self.__databook_bulk = {}
        self.__databook_bulk = value

    @property
    def tables(self):
        return self.__tables

    @tables.setter
    def tables(self, value):
        self.__tables = []
        self.__tables = value

    def load_reference(self, custom_ref: CustomRef | None) -> dict[str, dict]:
        '''
        load reference data from file

        Parameters
        ----------
        custom_ref : str
            custom reference file path to reference file

        Returns
        -------
        reference : dict
            reference data
        '''
        # current dir
        current_path = os.path.join(os.path.dirname(__file__))

        # Go back to the parent directory (pyThermoDB)
        parent_path = os.path.abspath(os.path.join(current_path, '..'))

        # Now navigate to the data folder
        data_path = os.path.join(parent_path, 'config')

        # relative
        config_path = os.path.join(data_path, 'reference.yml')

        with open(config_path, 'r') as f:
            reference = yaml.load(f, Loader=yaml.FullLoader)

        # update reference local
        self.__reference_local_no = len(reference['REFERENCES'])

        # check custom reference
        if custom_ref:
            # get data
            custom_reference = custom_ref.load_ref()
            # merge data
            reference['REFERENCES'].update(custom_reference)

        # log
        # <class 'dict'>
        # print(type(reference))
        return reference

    @staticmethod
    def load_custom_reference(
        custom_ref: CustomRef,
        save_to_file: bool = False,
        file_format: Literal['txt', 'yml'] = 'txt',
        file_name: Optional[str] = None,
        output_dir: Optional[str] = None
    ) -> Dict[str, Any] | None:
        '''
        Load custom reference data from file

        Parameters
        ----------
        custom_ref : CustomRef | None
            custom reference object
        save_to_file : bool, optional
            If True, save the custom reference to a txt file, by default False
        file_format : Literal['txt', 'yml'], optional
            Format of the file to save the custom reference, by default 'txt'. Options are 'txt' or 'yml'.
        file_name : str, optional
            Name of the file to save the custom reference, by default None.
        output_dir : str, optional
            Directory to save the custom reference file, by default None.

        Returns
        -------
        dict[str, dict]
            custom reference data
        '''
        try:
            # NOTE: check custom_ref
            if not isinstance(custom_ref, CustomRef):
                logging.warning("Custom reference is not provided or invalid!")
                return {}

            # NOTE: load custom reference
            if custom_ref:
                # check if directory is provided
                if output_dir is None:
                    # use current working directory
                    output_dir = os.getcwd()

                # check if directory exists
                if not os.path.exists(output_dir):
                    # create directory
                    os.makedirs(output_dir)

                # SECTION: load custom reference
                ref = custom_ref.load_ref()

                # check if ref is empty
                if not ref:
                    logging.warning("Custom reference is empty!")
                    return {}

                # check if file_name is provided
                if file_name is None:
                    # use default file name
                    if file_format == 'txt':
                        file_name = "custom_reference.txt"
                    elif file_format == 'yml':
                        file_name = "custom_reference.yml"
                    else:
                        logging.warning(
                            "Invalid file format! Use 'txt' or 'yml'.")
                        return {}
                else:
                    # set name
                    file_name = file_name.strip() + f".{file_format}"

                if save_to_file:
                    # build the full file path using directory and file_name
                    file_path = os.path.join(output_dir, file_name)

                    # check file format
                    if file_format == 'txt':
                        # ! to txt file
                        with open(file_path, "w") as f:
                            # `indent=4` for nice formatting
                            json.dump(ref, f, indent=4)
                    elif file_format == 'yml':
                        # ! to yaml file
                        with open(file_path, "w") as f:
                            # `default_flow_style=False` for nice formatting
                            yaml.dump(ref, f, sort_keys=False)
                    else:
                        logging.warning(
                            "Invalid file format! Use 'txt' or 'yml'.")

                return ref
            else:
                return {}
        except Exception as e:
            logging.error(f"Error loading custom reference: {e}")
            return {}

    def select_reference(self, reference: str) -> dict:
        '''
        Select a reference from the loaded references

        Parameters
        ----------
        reference : str
            reference name

        '''
        try:
            # check
            if reference not in self.__reference['REFERENCES']:
                raise ValueError(f"Reference {reference} not found!")

            # get reference
            selected_ref = self.__reference['REFERENCES'][reference]

            # return
            return selected_ref
        except Exception as e:
            raise Exception(f"select reference error! {e}")

    def load_symbols(self, custom_ref: CustomRef | None) -> dict:
        '''
        Load symbols used in the databooks

        Parameters
        ----------
        None

        Returns
        -------
        symbols : list
            list of symbols
        '''
        try:
            # current dir
            current_path = os.path.join(os.path.dirname(__file__))

            # Go back to the parent directory (pyThermoDB)
            parent_path = os.path.abspath(os.path.join(current_path, '..'))

            # Now navigate to the data folder
            data_path = os.path.join(parent_path, 'config')

            # relative
            config_path = os.path.join(data_path, 'symbols.yml')

            with open(config_path, 'r') as f:
                symbols = yaml.load(f, Loader=yaml.FullLoader)

            # check custom symbols
            if custom_ref:
                # get data
                custom_symbols = custom_ref.load_symbols()
                # check
                if len(custom_symbols) > 0:
                    # merge data
                    symbols['SYMBOLS'].update(custom_symbols)

            # return
            return symbols
        except Exception as e:
            raise Exception(f"symbol loading error! {e}")

    def load_descriptions(self):
        """
        Load reference descriptions for databooks
        """
        try:
            # references
            references = self.__reference['REFERENCES']

            # descriptions
            descriptions = {}

            for key, value in references.items():
                # databook name
                databook_name = key
                # databook id
                DATABOOK_ID = value.get('DATABOOK-ID', None)

                # init
                descriptions[databook_name] = {}
                # set
                descriptions[databook_name]['DATABOOK-ID'] = DATABOOK_ID

                # check tables
                for table, table_data in value.get('TABLES', {}).items():
                    # check
                    if 'DESCRIPTION' in table_data:
                        descriptions[databook_name][table] = {
                            'DATABOOK-ID': DATABOOK_ID,
                            'TABLE-ID': table_data.get('TABLE-ID', None),
                            'DESCRIPTION': table_data['DESCRIPTION']
                        }
                    else:
                        descriptions[databook_name][table] = {
                            'DATABOOK-ID': DATABOOK_ID,
                            'TABLE-ID': table_data.get('TABLE-ID', None),
                            'DESCRIPTION': None
                        }

            # return
            return descriptions
        except Exception as e:
            raise Exception(f"load_descriptions error! {e}")

    def get_symbols(self) -> tuple[dict, list, str, pd.DataFrame]:
        '''
        Get symbols

        Parameters
        ----------
        None

        Returns
        -------
        symbols : dict
            symbols
        '''
        try:
            # dict
            res = self.symbols['SYMBOLS']
            # list
            res_list = [(value, key) for key, value in res.items()]
            # json
            res_json = json.dumps(res, indent=4)
            # dataframe
            res_df = pd.DataFrame(res_list, columns=['Symbol', 'Description'])

            # res
            return res, res_list, res_json, res_df

        except Exception as e:
            raise Exception(f"symbol loading error! {e}")

    def get_descriptions(self) -> tuple[dict, list, str, pd.DataFrame]:
        '''
        Get databook descriptions
        '''
        try:
            # dict
            res = self.__description
            # list
            res_list = [(value, key) for key, value in res.items()]
            # json
            res_json = json.dumps(res, indent=4)
            # dataframe
            res_df = pd.DataFrame(res_list, columns=['Tables', 'Descriptions'])

            # res
            return res, res_list, res_json, res_df
        except Exception as e:
            raise Exception(f"description loading error! {e}")

    def get_descriptions_by_databook(self, databook: str) -> dict:
        '''
        Get descriptions by databook

        Parameters
        ----------
        databook : str
            databook name

        Returns
        -------
        descriptions : dict
            descriptions of the databook
        '''
        try:
            # check
            if databook not in self.__description:
                raise ValueError(f"Databook {databook} not found!")

            # get descriptions
            descriptions = self.__description[databook]

            # return
            return descriptions
        except Exception as e:
            raise Exception(f"description loading error! {e}")

    def get_databook_bulk(self) -> dict[str, list[DataBookTableTypes]]:
        '''
        Get databook bulk

        Parameters
        ----------
        None

        Returns
        -------
        databook_list : dict
            databook dict
        '''
        try:
            databook_list = {}
            references = self.__reference['REFERENCES']

            for databook, databook_data in references.items():
                # log
                # <class 'str'> <class 'dict'>
                # print(type(databook), type(databook_data))
                # databook name
                # databook_name = databook

                # databook id
                # databook_id = databook_data.get('DATABOOK-ID', None)

                tables = []
                for table, table_data in databook_data.get('TABLES', {}).items():
                    # log
                    # <class 'str' > <class 'dict' >
                    # print(type(table), type(table_data))

                    # NOTE: description
                    description = table_data.get('DESCRIPTION', None)

                    # NOTE: table id
                    table_id = table_data.get('TABLE-ID', -1)

                    # NOTE: table values
                    table_values = table_data.get('VALUES', None)

                    # NOTE: table structure
                    table_structure = table_data.get('STRUCTURE', None)

                    # NOTE: table reference
                    external_references = table_data.get(
                        'EXTERNAL-REFERENCES', None)

                    # SECTION: reference indicators
                    # ? DATA,
                    # ? EQUATIONS,
                    # ? MATRIX-DATA OR MATRIX-SYMBOL,
                    # ? MATRIX-EQUATIONS
                    # ! check EQUATIONS exists
                    if 'EQUATIONS' in table_data:
                        # eq
                        _eq = []
                        for eq, eq_data in table_data['EQUATIONS'].items():
                            # save
                            _eq.append(eq_data)

                        # NOTE: parse equations
                        _eq_formatted = self.__eq_formatter(_eq)

                        # save
                        tables.append({
                            'table_id': table_id,
                            'table': table,
                            'description': description,
                            'equations': _eq_formatted,
                            'data': None,
                            'matrix_equations': None,
                            'matrix_data': None,
                            'table_type': TableTypes.EQUATIONS.value,
                            'table_values': table_values,
                            'table_structure': table_structure,
                            'external_references': external_references
                        })
                        # reset
                        _eq = []
                    # ! check MATRIX-EQUATION
                    elif 'MATRIX-EQUATIONS' in table_data:
                        # eq
                        _eq = []
                        for eq, eq_data in table_data['MATRIX-EQUATIONS'].items():
                            # save
                            _eq.append(eq_data)

                        # save
                        tables.append({
                            'table_id': table_id,
                            'table': table,
                            'description': description,
                            'equations': None,
                            'data': None,
                            'matrix_equations': _eq,
                            'matrix_data': None,
                            'table_type': TableTypes.MATRIX_EQUATIONS.value,
                            'table_values': table_values,
                            'table_structure': table_structure,
                            'external_references': external_references
                        })
                        # reset
                        _eq = []
                    # ! check DATA
                    elif 'DATA' in table_data:
                        # data
                        data = table_data.get('DATA', [])

                        # REVIEW: generate table structure
                        table_structure = data if table_structure is None else table_structure
                        # set
                        if isinstance(data, list):
                            # check data
                            if len(data) == 0:
                                data = table_structure

                        # save
                        tables.append({
                            'table_id': table_id,
                            'table': table,
                            'description': description,
                            'equations': None,
                            'data': data,
                            'matrix_equations': None,
                            'matrix_data': None,
                            'table_type': TableTypes.DATA.value,
                            'table_values': table_values,
                            'table_structure': table_structure,
                            'external_references': external_references
                        })
                    # ! check MATRIX-DATA
                    elif ('MATRIX-DATA' in table_data) or ('MATRIX-SYMBOL' in table_data):
                        # matrix-data (data)
                        # NOTE: matrix-data
                        # including COLUMNS, SYMBOL, UNIT, CONVERSION, MATRIX-SYMBOL
                        matrix_data = table_data.get('MATRIX-DATA', {})

                        # NOTE: matrix-symbol
                        matrix_symbol = table_data.get('MATRIX-SYMBOL', None)

                        # embedded symbol
                        if matrix_symbol:
                            matrix_data['MATRIX-SYMBOL'] = matrix_symbol

                        # NOTE: table items
                        table_items = table_data.get('ITEMS', None)

                        # embedded symbol
                        if table_items:
                            matrix_data['ITEMS'] = table_items

                        # NOTE: table structure
                        if table_structure is not None:
                            # update
                            for k, v in table_structure.items():
                                # update
                                matrix_data[k] = v

                        # save
                        tables.append({
                            'table_id': table_id,
                            'table': table,
                            'description': description,
                            'equations': None,
                            'data': None,
                            'matrix_equations': None,
                            'matrix_data': matrix_data,
                            'table_type': TableTypes.MATRIX_DATA.value,
                            'table_values': table_values,
                            'table_structure': table_structure,
                            'table_items': table_items,
                            'external_references': external_references
                        })

                # save
                databook_list[databook] = tables

            # return
            return databook_list
        except Exception as e:
            raise Exception(f"databook loading error! {e}")

    def get_databooks(self) -> tuple[list[str], pd.DataFrame, str]:
        '''
        Get a list of databook

        Parameters
        ----------
        None

        Returns
        -------
        _db : list
            databook list
        databook_df : pd.DataFrame
            databook dataframe
        databook_json : str
            databook json

        Notes
        ------
        1. _db is the name of all books (databooks)
        '''
        try:
            # databook list
            _db = list(self.__databook_bulk.keys())
            # add id
            res = [(db, f"[{i+1}]") for i, db in enumerate(_db)]

            # create dict
            databook_dict = {
                f"databook-{i+1}": str(db) for i, db in enumerate(_db)
            }
            # create json
            databook_json = json.dumps(databook_dict, indent=4)

            # dataframe
            # column name
            column_name = "Databooks"
            databook_df = pd.DataFrame(res, columns=[column_name, "Id"])
            # return
            return _db, databook_df, databook_json

        except Exception as e:
            raise Exception(f"databook loading error! {e}")

    def get_databook_id(
        self,
        databook: str,
        res_format: Literal[
            'str', 'json', 'dict', 'int'
        ] = 'json'
    ) -> str | int | dict[str, str]:
        '''
        Get databook id

        Parameters
        ----------
        databook : str | int | dict
            databook name

        Returns
        -------
        databook_id : str
            databook id

        Notes
        -----
        1. databook id is non-zero-based
        2. if databook is not found, 'Databook not found!' is returned
        '''
        try:
            # check
            if not isinstance(databook, str):
                raise Exception("databook must be string!")

            # find
            for i, db in enumerate(self.__databook):
                if db == databook:
                    db_id = str(i+1)

                    # check
                    if res_format == 'str':
                        return db_id
                    elif res_format == 'int':
                        return int(db_id)
                    elif res_format == 'json':
                        return json.dumps({"databook_id": db_id}, indent=4)
                    elif res_format == 'dict':
                        return {"databook_id": db_id}
                    else:
                        raise ValueError(
                            "res_format must be 'str', 'json', or 'dict'!")
            # return
            return 'Databook not found!'
        except Exception as e:
            raise Exception(f"databook id loading error! {e}")

    def get_tables(
            self,
            databook
    ) -> tuple[list[list[str]], pd.DataFrame, str, dict[str, str]]:
        '''
        Get a table list of selected databook

        Parameters
        ----------
        databook : str
            databook name

        Returns
        -------
        tables : list | pandas.DataFrame | str
            table list of selected databook
        '''
        try:
            # list tables
            if isinstance(databook, str):
                _dbs = self.__databook_bulk[databook]
            elif isinstance(databook, int):
                _dbs = self.__databook_bulk[self.__databook[databook]]
            # list
            tables: list[list[str]] = []
            # check table and equations
            for i, tb in enumerate(_dbs):
                # check
                # ! equation
                if tb['equations'] is not None:
                    tables.append([tb['table'], "equation",
                                  f"[{i+1}]"])
                # ! data
                elif tb['data'] is not None:
                    tables.append([tb['table'], "data", f"[{i+1}]"])
                # ! matrix-data
                elif tb['matrix_data'] is not None:
                    tables.append(
                        [tb['table'], "matrix-data", f"[{i+1}]"])
                # ! matrix-equation
                elif tb['matrix_equations'] is not None:
                    tables.append(
                        [tb['table'], "matrix-equation", f"[{i+1}]"])
                else:
                    raise Exception("data type unknown!")

            # dataframe
            # column name
            column_name = f"Tables in {databook} databook"

            # convert to json
            tables_dict = {f"table-{i+1}": tb[0]
                           for i, tb in enumerate(tables)}
            # convert to json
            tables_json = json.dumps(tables_dict, indent=4)

            # ! set table dataframe
            tables_df = pd.DataFrame(
                tables, columns=[column_name, "Type", "Id"])
            # return
            return tables, tables_df, tables_json, tables_dict
        except Exception as e:
            raise Exception(f"table loading err! {e}")

    def get_table_type(self, databook: int, table_id: int) -> str:
        '''
        Get a table type

        Parameters
        ----------
        databook : int
            databook id (non-zero-based)
        table_id : int
            table id (non-zero-based)

        Returns
        -------
        table_type : str
            table type
        '''
        try:
            # get table
            tb = self.get_table(databook-1, table_id-1)

            # filter
            filter_keys = [enum.value for enum in TableTypes]

            # table data type
            tb_bulk = {key: value for key, value in tb.items(
            ) if key in filter_keys and value is not None}

            # table type
            tb_type = ''

            # check
            if len(tb_bulk) == 1:
                tb_type, _ = tb_bulk.popitem()
            else:
                raise Exception("table type unknown!")

            # return
            return tb_type

        except Exception as e:
            raise Exception(f"table info loading err! {e}")

    def get_table(self,
                  databook: str | int | list[DataBookTableTypes],
                  table: int | str) -> DataBookTableTypes:
        '''
        Get a table with respect to databook and table id or name

        Parameters
        ----------
        databook : str | int | list
            databook name or id (zero-based id)
        table : int
            table id (zero-based id) or name

        Returns
        -------
        table : DataBookTableTypes
            selected table based on databook and table id or name
        '''
        try:
            # select databook
            if isinstance(databook, str):
                databook_set = self.databook_bulk[databook]
            elif isinstance(databook, int):
                databook_set = self.databook_bulk[self.__databook[databook]]
            else:
                # for previously extracted databook
                databook_set = databook

            # ! if databook list
            # list
            # selected_tb: DataBookTableTypes
            selected_tb = None

            # SECTION: set table type
            def set_table_type(tb):
                # check table type
                if 'equations' in tb and tb['equations'] is not None:
                    return TableTypes.EQUATIONS.value
                elif 'data' in tb and tb['data'] is not None:
                    return TableTypes.DATA.value
                elif 'matrix_data' in tb and tb['matrix_data'] is not None:
                    return TableTypes.MATRIX_DATA.value
                elif 'matrix_equations' in tb and tb['matrix_equations'] is not None:
                    return TableTypes.MATRIX_EQUATIONS.value
                else:
                    raise Exception("table type unknown!")

            # by table id
            if isinstance(table, int):
                # check table and equations
                for i, tb in enumerate(databook_set):
                    # check table id
                    if i == table:
                        selected_tb = DataBookTableTypes(**tb)
                        # NOTE: check table type
                        # tb_name_ = selected_tb['table']
                        # set
                        selected_tb['table_type'] = set_table_type(tb)
                        break
            # by table name
            elif isinstance(table, str):
                # check table name
                for i, tb in enumerate(databook_set):
                    # check table name
                    if tb['table'] == table:
                        selected_tb = DataBookTableTypes(**tb)
                        # NOTE: check table type
                        # tb_name_ = selected_tb['table']
                        # set
                        selected_tb['table_type'] = set_table_type(tb)
                        break
            else:
                raise Exception("Invalid table type")

            # NOTE: check selected table
            if selected_tb is None:
                raise Exception("table not found!")
            # return
            return selected_tb
        except Exception as e:
            raise Exception(f"table loading err! {e}")

    def get_table_id(self,
                     databook: str | int,
                     table: str,
                     res_format: Literal[
                         'str', 'json', 'dict'
                     ] = 'json') -> str | dict[str, str]:
        '''
        Get table id

        Parameters
        ----------
        databook : str | int
            databook name or id
        table : str
            table name

        Returns
        -------
        table_id : str | dict[str, str]
            table id
        '''
        try:
            # select databook
            if isinstance(databook, str):
                databook_set = self.databook_bulk[databook]
            elif isinstance(databook, int):
                databook_set = self.databook_bulk[self.__databook[databook]]
            else:
                raise ValueError("databook must be str or int!")

            # table id
            table_id = 'Table id not found!'

            # check table and equations
            for i, tb in enumerate(databook_set):
                # check table id
                if tb['table'] == table:
                    table_id = str(i+1)
                    break

            # check
            if res_format == 'str':
                return table_id
            elif res_format == 'json':
                return json.dumps({"table_id": table_id}, indent=4)
            elif res_format == 'dict':
                return {"table_id": table_id}
            else:
                raise ValueError("res_format must be 'str' or 'json'!")

        except Exception as e:
            raise Exception(f"table id loading err! {e}")

    def get_table_values(self, databook: str | int, table: str | int):
        '''
        Get table values

        Parameters
        ----------
        databook : str | int
            databook name or id
        table : str | int
            table name or id

        Returns
        -------
        table_values : list
            table values
        '''
        try:
            # NOTE: find databook
            db, db_name, db_id = self.find_databook(databook)

            # NOTE: find table
            tb_id, tb_name = self.find_table(db_name, table)

            # NOTE: get table
            tb = self.get_table(db_name, tb_name)

            return tb

        except Exception as e:
            raise Exception(f"table values loading err! {e}")

    def find_databook(
        self,
        databook: str | int
    ) -> tuple[list[DataBookTableTypes], str, int]:
        '''
        Find a databook

        Parameters
        ----------
        databook : str | int
            databook name/id

        Returns
        -------
        selected_databook: object
            selected databook
        databook_name: str
            databook name
        databook_id: int
            databook id

        Notes
        -----
        if databook is int, the zero-based id is returned
        '''
        try:
            # set
            databook_name = ''

            # SECTION: check string or int
            if isinstance(databook, str):
                # check if str is number
                databook_type = is_str_number(databook)
                # convert to int
                if databook_type:
                    databook = int(databook)

            # SECTION: find databook id and name
            if isinstance(databook, int):
                # convert to zero-based id
                databook_id = databook-1
                databook_name = self.databook[databook_id]
            elif isinstance(databook, str):
                # find databook
                for i, item in enumerate(self.databook):
                    if item == databook.strip():
                        databook_id = i
                        databook_name = item
                        break
            else:
                raise ValueError("databook must be int or str")

            # NOTE: set databook
            selected_databook = self.databook_bulk[databook_name]
            # check
            if not selected_databook:
                logger.error("Databook selected not found!")

            # res
            return selected_databook, databook_name, databook_id
        except Exception as e:
            raise Exception(f"databook finding err! {e}")

    def find_table(
            self,
            databook: str | int,
            table: str | int
    ) -> tuple[int, str]:
        '''
        Finds table id through searching databook id and table name

        Parameters
        ----------
        databook : int | str
            databook id or name
        table : id | str
            table name

        Returns
        -------
        table_id : int
            table id (zero-based)
        table_name : str
            table name

        Notes
        -----
        if table is int, the zero-based id is returned
        '''
        try:
            # set
            table_id, table_name = 0, ''

            # SECTION: find databook zero-base id (real)
            selected_databook, databook_name, databook_id = self.find_databook(
                databook
            )

            # SECTION: check table input type
            if isinstance(table, str):
                # check if str is number
                table_type = is_str_number(table)
                # convert to int
                if table_type:
                    table = int(table)

            # SECTION: find table id and name
            if isinstance(table, int):
                # convert to zero-based id
                table_id = table-1
                # table name
                table_name = selected_databook[table_id]['table']
            elif isinstance(table, str):
                # find table id
                for i, tb in enumerate(selected_databook):
                    if tb['table'] == table.strip():
                        table_id = i
                        # table name
                        table_name = tb['table']
                        break
            else:
                raise ValueError("table must be int or str")

            # return
            return table_id, table_name

        except Exception as e:
            raise Exception('Finding table id failed!, ', e)

    def find_table_source(
            self,
            table: str | int
    ) -> dict[str, str | int]:
        """
        Find table source (databook name and id)

        Parameters
        ----------
        table : str | int
            table name or id (non-zero-based)

        Returns
        -------
        dict :
            databook_name : str
                databook name
            databook_id : int
                databook id
            table_name : str
                table name
            table_id : int
                table id
        """
        try:
            # set
            table_id, table_name = 0, ''
            databook_id = 0
            db = ''

            # check table
            for i, db in enumerate(self.databook):
                # get databook name and id
                # databook_name, databook_id = db['name'], i
                databook_id = self.get_databook_id(db, res_format='int')
                # check
                if not isinstance(databook_id, int):
                    raise ValueError("databook id must be int!")
                if databook_id == 0:
                    raise ValueError("databook id must be non-zero-based!")

                # find table
                for j, tb in enumerate(self.databook_bulk[db]):
                    if isinstance(table, int):

                        # check
                        if table == 0:
                            raise ValueError(
                                "table id must be non-zero-based!")

                        # check
                        if tb['table_id'] == table:
                            table_id = tb['table_id']
                            table_name = tb['table']

                            # check
                            if not table_id:
                                raise ValueError("table id not found!")

                            # get data type
                            data_type = self.get_table_type(
                                databook_id, int(table_id))

                            # return
                            return {
                                'databook_name': db,
                                'databook_id': databook_id,
                                'table_name': table_name,
                                'table_id': table_id,
                                'data_type': data_type
                            }

                    elif isinstance(table, str):
                        # check
                        if tb['table'] == table.strip():
                            table_id = tb['table_id']
                            table_name = tb['table']

                            # check
                            if not table_id:
                                raise ValueError("table id not found!")

                            # get data type
                            data_type = self.get_table_type(
                                databook_id, int(table_id))

                            # return
                            return {
                                'databook_name': db,
                                'databook_id': databook_id,
                                'table_name': table_name,
                                'table_id': table_id,
                                'data_type': data_type
                            }
                    else:
                        raise ValueError("table must be int or str")

            # return
            return {}
        except Exception as e:
            raise Exception('Finding table source failed!', e)

    def __parse_equation(
            self,
            eq_data: List[str]
    ):
        '''
        Parse equation data into a dictionary including equation args, parameters, returns

        Parameters
        ----------
        eq_data : dict
            equation data
        '''
        try:
            # check
            if not isinstance(eq_data, list):
                raise ValueError("eq_data must be a list!")

            # init
            eq_dict = {}
            eq_dict['ARGS'] = {}
            eq_dict['PARMS'] = {}
            eq_dict['RETURNS'] = {}
            eq_dict['BODY'] = []

            # NOTE: value generator
            def val_generator(d):
                '''Generate value'''
                # check 3 |
                if "|" in d:
                    # split
                    match_res = d.split("|")
                    # check
                    if len(match_res) != 3:
                        raise ValueError(
                            f"{d} must be 3 elements!")

                    # key
                    key = match_res[0].strip()
                    # name
                    name = key
                    # symbol
                    symbol = match_res[1].strip()
                    # unit
                    unit = match_res[2].strip()

                    # set
                    val = {
                        'name': name,
                        'symbol': symbol,
                        'unit': unit
                    }
                else:
                    raise Exception(
                        f"Invalid value format! {d} must be 3 elements!")

                return key, val

            # SECTION: parse equation data
            # loop through eq_data
            for eq in eq_data:
                # check
                if isinstance(eq, str):
                    # parse equation body
                    body_ = eq

                    # NOTE: parse to extract args
                    # regex
                    regex = r"args\['([^']+)'\]"
                    # find all matches
                    matches = re.findall(regex, body_)
                    # check
                    if matches:
                        # loop through matches
                        for match in matches:
                            # ! val generator
                            key, val = val_generator(match)
                            symbol = val['symbol']
                            # check
                            if match not in eq_dict['ARGS']:
                                # set
                                eq_dict['ARGS'][key] = val
                                # set body
                                body_ = body_.replace(
                                    f"'{match}'", f"'{symbol}'")

                    # NOTE: parse to extract parameters
                    # regex
                    regex = r"parms\['([^']+)'\]"
                    # find all matches
                    matches = re.findall(regex, body_)
                    # check
                    if matches:
                        # loop through matches
                        for match in matches:
                            # ! val generator
                            key, val = val_generator(match)
                            symbol = val['symbol']
                            # check
                            if match not in eq_dict['PARMS']:
                                # set
                                eq_dict['PARMS'][key] = val
                                # set body
                                body_ = body_.replace(
                                    f"'{match}'", f"'{symbol}'")

                    # NOTE: parse to extract returns
                    # regex
                    regex = r"res\['([^']+)'\]"
                    # find all matches
                    matches = re.findall(regex, body_)
                    # check
                    if matches:
                        # loop through matches
                        for match in matches:
                            # ! val generator
                            key, val = val_generator(match)
                            symbol = val['symbol']
                            # check
                            if match not in eq_dict['RETURNS']:
                                # set
                                eq_dict['RETURNS'][key] = val
                                # set body
                                body_ = body_.replace(f"res['{match}']", "res")

                # updated body
                # set body
                eq_dict['BODY'].append(body_)
            # return
            return eq_dict
        except Exception as e:
            raise Exception(f"parse_equation error! {e}")

    def __eq_formatter(self, eqs: List):
        '''
        Format equations
        '''
        try:
            # NOTE: eqs
            eqs_formatted = []

            # NOTE: check eqs
            for eq in eqs:
                # check keys
                if "ARGS" not in eq or "PARMS" not in eq or "RETURNS" not in eq:
                    # parse eq to generate equation structure
                    eq_ = self.equation_formatter(eq)
                    eqs_formatted.append(eq_)
                else:
                    eqs_formatted.append(eq)

            # res
            return eqs_formatted
        except Exception as e:
            raise Exception(f"equation formatting error! {e}")

    def equation_formatter(self, equation_src: Dict | str) -> Dict[str, Any]:
        '''
        Check equation format

        Parameters
        ----------
        equation_src : str | dict
            equation source (file path string or dict)
        '''
        try:
            # SECTION: path check
            if isinstance(equation_src, str):
                # check file
                if not os.path.isfile(equation_src):
                    raise FileNotFoundError(f"File not found: {equation_src}")

                # NOTE: load equation file (yml format)
                with open(equation_src, 'r') as f:
                    equations = yaml.load(f, Loader=yaml.FullLoader)
            elif isinstance(equation_src, dict):
                # NOTE: check if dict
                equations = equation_src

            # SECTION: check equation format
            # NOTE: check
            if 'BODY' not in equations.keys():
                raise ValueError("equation key `BODY` not found!")

            # NOTE: get equation body
            body_ = equations['BODY']

            # NOTE: parse
            parse_res = self.__parse_equation(body_)

            # NOTE: check other equations
            body_integral = equations.get('BODY-INTEGRAL', None)
            body_first_derivative = equations.get(
                'BODY-FIRST-DERIVATIVE', None)
            body_second_derivative = equations.get(
                'BODY-SECOND-DERIVATIVE', None)

            # check
            if body_integral is not None:
                # check
                if body_integral != 'None' and body_integral != 'NONE':
                    # parse
                    parse_ = self.__parse_equation(body_integral)
                    # add to res
                    parse_res['BODY-INTEGRAL'] = parse_['BODY']
            else:
                parse_res['BODY-INTEGRAL'] = None

            if body_first_derivative is not None:
                # check
                if body_first_derivative != 'None' and body_first_derivative != 'NONE':
                    # parse
                    parse_ = self.__parse_equation(body_first_derivative)
                    # add to res
                    parse_res['BODY-FIRST-DERIVATIVE'] = parse_['BODY']
            else:
                parse_res['BODY-FIRST-DERIVATIVE'] = None

            if body_second_derivative is not None:
                # check
                if body_second_derivative != 'None' and body_second_derivative != 'NONE':
                    # parse
                    parse_ = self.__parse_equation(body_second_derivative)
                    # add to res
                    parse_res['BODY-SECOND-DERIVATIVE'] = parse_['BODY']
            else:
                parse_res['BODY-SECOND-DERIVATIVE'] = None

            # res
            return parse_res
        except FileNotFoundError:
            raise FileNotFoundError(f"File not found: {equation_src}")
        except Exception as e:
            raise Exception(f"equation format checker error! {e}")

__eq_formatter(eqs)

Format equations

Source code in pyThermoDB/manager/managedata.py

def __eq_formatter(self, eqs: List):
    '''
    Format equations
    '''
    try:
        # NOTE: eqs
        eqs_formatted = []

        # NOTE: check eqs
        for eq in eqs:
            # check keys
            if "ARGS" not in eq or "PARMS" not in eq or "RETURNS" not in eq:
                # parse eq to generate equation structure
                eq_ = self.equation_formatter(eq)
                eqs_formatted.append(eq_)
            else:
                eqs_formatted.append(eq)

        # res
        return eqs_formatted
    except Exception as e:
        raise Exception(f"equation formatting error! {e}")

__parse_equation(eq_data)

Parse equation data into a dictionary including equation args, parameters, returns

Parameters

eq_data : dict equation data

Source code in pyThermoDB/manager/managedata.py

def __parse_equation(
        self,
        eq_data: List[str]
):
    '''
    Parse equation data into a dictionary including equation args, parameters, returns

    Parameters
    ----------
    eq_data : dict
        equation data
    '''
    try:
        # check
        if not isinstance(eq_data, list):
            raise ValueError("eq_data must be a list!")

        # init
        eq_dict = {}
        eq_dict['ARGS'] = {}
        eq_dict['PARMS'] = {}
        eq_dict['RETURNS'] = {}
        eq_dict['BODY'] = []

        # NOTE: value generator
        def val_generator(d):
            '''Generate value'''
            # check 3 |
            if "|" in d:
                # split
                match_res = d.split("|")
                # check
                if len(match_res) != 3:
                    raise ValueError(
                        f"{d} must be 3 elements!")

                # key
                key = match_res[0].strip()
                # name
                name = key
                # symbol
                symbol = match_res[1].strip()
                # unit
                unit = match_res[2].strip()

                # set
                val = {
                    'name': name,
                    'symbol': symbol,
                    'unit': unit
                }
            else:
                raise Exception(
                    f"Invalid value format! {d} must be 3 elements!")

            return key, val

        # SECTION: parse equation data
        # loop through eq_data
        for eq in eq_data:
            # check
            if isinstance(eq, str):
                # parse equation body
                body_ = eq

                # NOTE: parse to extract args
                # regex
                regex = r"args\['([^']+)'\]"
                # find all matches
                matches = re.findall(regex, body_)
                # check
                if matches:
                    # loop through matches
                    for match in matches:
                        # ! val generator
                        key, val = val_generator(match)
                        symbol = val['symbol']
                        # check
                        if match not in eq_dict['ARGS']:
                            # set
                            eq_dict['ARGS'][key] = val
                            # set body
                            body_ = body_.replace(
                                f"'{match}'", f"'{symbol}'")

                # NOTE: parse to extract parameters
                # regex
                regex = r"parms\['([^']+)'\]"
                # find all matches
                matches = re.findall(regex, body_)
                # check
                if matches:
                    # loop through matches
                    for match in matches:
                        # ! val generator
                        key, val = val_generator(match)
                        symbol = val['symbol']
                        # check
                        if match not in eq_dict['PARMS']:
                            # set
                            eq_dict['PARMS'][key] = val
                            # set body
                            body_ = body_.replace(
                                f"'{match}'", f"'{symbol}'")

                # NOTE: parse to extract returns
                # regex
                regex = r"res\['([^']+)'\]"
                # find all matches
                matches = re.findall(regex, body_)
                # check
                if matches:
                    # loop through matches
                    for match in matches:
                        # ! val generator
                        key, val = val_generator(match)
                        symbol = val['symbol']
                        # check
                        if match not in eq_dict['RETURNS']:
                            # set
                            eq_dict['RETURNS'][key] = val
                            # set body
                            body_ = body_.replace(f"res['{match}']", "res")

            # updated body
            # set body
            eq_dict['BODY'].append(body_)
        # return
        return eq_dict
    except Exception as e:
        raise Exception(f"parse_equation error! {e}")

equation_formatter(equation_src)

Check equation format

Parameters

equation_src : str | dict equation source (file path string or dict)

Source code in pyThermoDB/manager/managedata.py

def equation_formatter(self, equation_src: Dict | str) -> Dict[str, Any]:
    '''
    Check equation format

    Parameters
    ----------
    equation_src : str | dict
        equation source (file path string or dict)
    '''
    try:
        # SECTION: path check
        if isinstance(equation_src, str):
            # check file
            if not os.path.isfile(equation_src):
                raise FileNotFoundError(f"File not found: {equation_src}")

            # NOTE: load equation file (yml format)
            with open(equation_src, 'r') as f:
                equations = yaml.load(f, Loader=yaml.FullLoader)
        elif isinstance(equation_src, dict):
            # NOTE: check if dict
            equations = equation_src

        # SECTION: check equation format
        # NOTE: check
        if 'BODY' not in equations.keys():
            raise ValueError("equation key `BODY` not found!")

        # NOTE: get equation body
        body_ = equations['BODY']

        # NOTE: parse
        parse_res = self.__parse_equation(body_)

        # NOTE: check other equations
        body_integral = equations.get('BODY-INTEGRAL', None)
        body_first_derivative = equations.get(
            'BODY-FIRST-DERIVATIVE', None)
        body_second_derivative = equations.get(
            'BODY-SECOND-DERIVATIVE', None)

        # check
        if body_integral is not None:
            # check
            if body_integral != 'None' and body_integral != 'NONE':
                # parse
                parse_ = self.__parse_equation(body_integral)
                # add to res
                parse_res['BODY-INTEGRAL'] = parse_['BODY']
        else:
            parse_res['BODY-INTEGRAL'] = None

        if body_first_derivative is not None:
            # check
            if body_first_derivative != 'None' and body_first_derivative != 'NONE':
                # parse
                parse_ = self.__parse_equation(body_first_derivative)
                # add to res
                parse_res['BODY-FIRST-DERIVATIVE'] = parse_['BODY']
        else:
            parse_res['BODY-FIRST-DERIVATIVE'] = None

        if body_second_derivative is not None:
            # check
            if body_second_derivative != 'None' and body_second_derivative != 'NONE':
                # parse
                parse_ = self.__parse_equation(body_second_derivative)
                # add to res
                parse_res['BODY-SECOND-DERIVATIVE'] = parse_['BODY']
        else:
            parse_res['BODY-SECOND-DERIVATIVE'] = None

        # res
        return parse_res
    except FileNotFoundError:
        raise FileNotFoundError(f"File not found: {equation_src}")
    except Exception as e:
        raise Exception(f"equation format checker error! {e}")

find_databook(databook)

Find a databook

Parameters

databook : str | int databook name/id

Returns

selected_databook: object selected databook databook_name: str databook name databook_id: int databook id

Notes

if databook is int, the zero-based id is returned

Source code in pyThermoDB/manager/managedata.py

def find_databook(
    self,
    databook: str | int
) -> tuple[list[DataBookTableTypes], str, int]:
    '''
    Find a databook

    Parameters
    ----------
    databook : str | int
        databook name/id

    Returns
    -------
    selected_databook: object
        selected databook
    databook_name: str
        databook name
    databook_id: int
        databook id

    Notes
    -----
    if databook is int, the zero-based id is returned
    '''
    try:
        # set
        databook_name = ''

        # SECTION: check string or int
        if isinstance(databook, str):
            # check if str is number
            databook_type = is_str_number(databook)
            # convert to int
            if databook_type:
                databook = int(databook)

        # SECTION: find databook id and name
        if isinstance(databook, int):
            # convert to zero-based id
            databook_id = databook-1
            databook_name = self.databook[databook_id]
        elif isinstance(databook, str):
            # find databook
            for i, item in enumerate(self.databook):
                if item == databook.strip():
                    databook_id = i
                    databook_name = item
                    break
        else:
            raise ValueError("databook must be int or str")

        # NOTE: set databook
        selected_databook = self.databook_bulk[databook_name]
        # check
        if not selected_databook:
            logger.error("Databook selected not found!")

        # res
        return selected_databook, databook_name, databook_id
    except Exception as e:
        raise Exception(f"databook finding err! {e}")

find_table(databook, table)

Finds table id through searching databook id and table name

Parameters

databook : int | str databook id or name table : id | str table name

Returns

table_id : int table id (zero-based) table_name : str table name

Notes

if table is int, the zero-based id is returned

Source code in pyThermoDB/manager/managedata.py

def find_table(
        self,
        databook: str | int,
        table: str | int
) -> tuple[int, str]:
    '''
    Finds table id through searching databook id and table name

    Parameters
    ----------
    databook : int | str
        databook id or name
    table : id | str
        table name

    Returns
    -------
    table_id : int
        table id (zero-based)
    table_name : str
        table name

    Notes
    -----
    if table is int, the zero-based id is returned
    '''
    try:
        # set
        table_id, table_name = 0, ''

        # SECTION: find databook zero-base id (real)
        selected_databook, databook_name, databook_id = self.find_databook(
            databook
        )

        # SECTION: check table input type
        if isinstance(table, str):
            # check if str is number
            table_type = is_str_number(table)
            # convert to int
            if table_type:
                table = int(table)

        # SECTION: find table id and name
        if isinstance(table, int):
            # convert to zero-based id
            table_id = table-1
            # table name
            table_name = selected_databook[table_id]['table']
        elif isinstance(table, str):
            # find table id
            for i, tb in enumerate(selected_databook):
                if tb['table'] == table.strip():
                    table_id = i
                    # table name
                    table_name = tb['table']
                    break
        else:
            raise ValueError("table must be int or str")

        # return
        return table_id, table_name

    except Exception as e:
        raise Exception('Finding table id failed!, ', e)

find_table_source(table)

Find table source (databook name and id)

Parameters

table : str | int table name or id (non-zero-based)

Returns

dict : databook_name : str databook name databook_id : int databook id table_name : str table name table_id : int table id

Source code in pyThermoDB/manager/managedata.py

def find_table_source(
        self,
        table: str | int
) -> dict[str, str | int]:
    """
    Find table source (databook name and id)

    Parameters
    ----------
    table : str | int
        table name or id (non-zero-based)

    Returns
    -------
    dict :
        databook_name : str
            databook name
        databook_id : int
            databook id
        table_name : str
            table name
        table_id : int
            table id
    """
    try:
        # set
        table_id, table_name = 0, ''
        databook_id = 0
        db = ''

        # check table
        for i, db in enumerate(self.databook):
            # get databook name and id
            # databook_name, databook_id = db['name'], i
            databook_id = self.get_databook_id(db, res_format='int')
            # check
            if not isinstance(databook_id, int):
                raise ValueError("databook id must be int!")
            if databook_id == 0:
                raise ValueError("databook id must be non-zero-based!")

            # find table
            for j, tb in enumerate(self.databook_bulk[db]):
                if isinstance(table, int):

                    # check
                    if table == 0:
                        raise ValueError(
                            "table id must be non-zero-based!")

                    # check
                    if tb['table_id'] == table:
                        table_id = tb['table_id']
                        table_name = tb['table']

                        # check
                        if not table_id:
                            raise ValueError("table id not found!")

                        # get data type
                        data_type = self.get_table_type(
                            databook_id, int(table_id))

                        # return
                        return {
                            'databook_name': db,
                            'databook_id': databook_id,
                            'table_name': table_name,
                            'table_id': table_id,
                            'data_type': data_type
                        }

                elif isinstance(table, str):
                    # check
                    if tb['table'] == table.strip():
                        table_id = tb['table_id']
                        table_name = tb['table']

                        # check
                        if not table_id:
                            raise ValueError("table id not found!")

                        # get data type
                        data_type = self.get_table_type(
                            databook_id, int(table_id))

                        # return
                        return {
                            'databook_name': db,
                            'databook_id': databook_id,
                            'table_name': table_name,
                            'table_id': table_id,
                            'data_type': data_type
                        }
                else:
                    raise ValueError("table must be int or str")

        # return
        return {}
    except Exception as e:
        raise Exception('Finding table source failed!', e)

get_databook_bulk()

Get databook bulk

Parameters

None

Returns

databook_list : dict databook dict

Source code in pyThermoDB/manager/managedata.py

def get_databook_bulk(self) -> dict[str, list[DataBookTableTypes]]:
    '''
    Get databook bulk

    Parameters
    ----------
    None

    Returns
    -------
    databook_list : dict
        databook dict
    '''
    try:
        databook_list = {}
        references = self.__reference['REFERENCES']

        for databook, databook_data in references.items():
            # log
            # <class 'str'> <class 'dict'>
            # print(type(databook), type(databook_data))
            # databook name
            # databook_name = databook

            # databook id
            # databook_id = databook_data.get('DATABOOK-ID', None)

            tables = []
            for table, table_data in databook_data.get('TABLES', {}).items():
                # log
                # <class 'str' > <class 'dict' >
                # print(type(table), type(table_data))

                # NOTE: description
                description = table_data.get('DESCRIPTION', None)

                # NOTE: table id
                table_id = table_data.get('TABLE-ID', -1)

                # NOTE: table values
                table_values = table_data.get('VALUES', None)

                # NOTE: table structure
                table_structure = table_data.get('STRUCTURE', None)

                # NOTE: table reference
                external_references = table_data.get(
                    'EXTERNAL-REFERENCES', None)

                # SECTION: reference indicators
                # ? DATA,
                # ? EQUATIONS,
                # ? MATRIX-DATA OR MATRIX-SYMBOL,
                # ? MATRIX-EQUATIONS
                # ! check EQUATIONS exists
                if 'EQUATIONS' in table_data:
                    # eq
                    _eq = []
                    for eq, eq_data in table_data['EQUATIONS'].items():
                        # save
                        _eq.append(eq_data)

                    # NOTE: parse equations
                    _eq_formatted = self.__eq_formatter(_eq)

                    # save
                    tables.append({
                        'table_id': table_id,
                        'table': table,
                        'description': description,
                        'equations': _eq_formatted,
                        'data': None,
                        'matrix_equations': None,
                        'matrix_data': None,
                        'table_type': TableTypes.EQUATIONS.value,
                        'table_values': table_values,
                        'table_structure': table_structure,
                        'external_references': external_references
                    })
                    # reset
                    _eq = []
                # ! check MATRIX-EQUATION
                elif 'MATRIX-EQUATIONS' in table_data:
                    # eq
                    _eq = []
                    for eq, eq_data in table_data['MATRIX-EQUATIONS'].items():
                        # save
                        _eq.append(eq_data)

                    # save
                    tables.append({
                        'table_id': table_id,
                        'table': table,
                        'description': description,
                        'equations': None,
                        'data': None,
                        'matrix_equations': _eq,
                        'matrix_data': None,
                        'table_type': TableTypes.MATRIX_EQUATIONS.value,
                        'table_values': table_values,
                        'table_structure': table_structure,
                        'external_references': external_references
                    })
                    # reset
                    _eq = []
                # ! check DATA
                elif 'DATA' in table_data:
                    # data
                    data = table_data.get('DATA', [])

                    # REVIEW: generate table structure
                    table_structure = data if table_structure is None else table_structure
                    # set
                    if isinstance(data, list):
                        # check data
                        if len(data) == 0:
                            data = table_structure

                    # save
                    tables.append({
                        'table_id': table_id,
                        'table': table,
                        'description': description,
                        'equations': None,
                        'data': data,
                        'matrix_equations': None,
                        'matrix_data': None,
                        'table_type': TableTypes.DATA.value,
                        'table_values': table_values,
                        'table_structure': table_structure,
                        'external_references': external_references
                    })
                # ! check MATRIX-DATA
                elif ('MATRIX-DATA' in table_data) or ('MATRIX-SYMBOL' in table_data):
                    # matrix-data (data)
                    # NOTE: matrix-data
                    # including COLUMNS, SYMBOL, UNIT, CONVERSION, MATRIX-SYMBOL
                    matrix_data = table_data.get('MATRIX-DATA', {})

                    # NOTE: matrix-symbol
                    matrix_symbol = table_data.get('MATRIX-SYMBOL', None)

                    # embedded symbol
                    if matrix_symbol:
                        matrix_data['MATRIX-SYMBOL'] = matrix_symbol

                    # NOTE: table items
                    table_items = table_data.get('ITEMS', None)

                    # embedded symbol
                    if table_items:
                        matrix_data['ITEMS'] = table_items

                    # NOTE: table structure
                    if table_structure is not None:
                        # update
                        for k, v in table_structure.items():
                            # update
                            matrix_data[k] = v

                    # save
                    tables.append({
                        'table_id': table_id,
                        'table': table,
                        'description': description,
                        'equations': None,
                        'data': None,
                        'matrix_equations': None,
                        'matrix_data': matrix_data,
                        'table_type': TableTypes.MATRIX_DATA.value,
                        'table_values': table_values,
                        'table_structure': table_structure,
                        'table_items': table_items,
                        'external_references': external_references
                    })

            # save
            databook_list[databook] = tables

        # return
        return databook_list
    except Exception as e:
        raise Exception(f"databook loading error! {e}")

get_databook_id(databook, res_format='json')

Get databook id

Parameters

databook : str | int | dict databook name

Returns

databook_id : str databook id

Notes

1. databook id is non-zero-based
2. if databook is not found, 'Databook not found!' is returned

Source code in pyThermoDB/manager/managedata.py

def get_databook_id(
    self,
    databook: str,
    res_format: Literal[
        'str', 'json', 'dict', 'int'
    ] = 'json'
) -> str | int | dict[str, str]:
    '''
    Get databook id

    Parameters
    ----------
    databook : str | int | dict
        databook name

    Returns
    -------
    databook_id : str
        databook id

    Notes
    -----
    1. databook id is non-zero-based
    2. if databook is not found, 'Databook not found!' is returned
    '''
    try:
        # check
        if not isinstance(databook, str):
            raise Exception("databook must be string!")

        # find
        for i, db in enumerate(self.__databook):
            if db == databook:
                db_id = str(i+1)

                # check
                if res_format == 'str':
                    return db_id
                elif res_format == 'int':
                    return int(db_id)
                elif res_format == 'json':
                    return json.dumps({"databook_id": db_id}, indent=4)
                elif res_format == 'dict':
                    return {"databook_id": db_id}
                else:
                    raise ValueError(
                        "res_format must be 'str', 'json', or 'dict'!")
        # return
        return 'Databook not found!'
    except Exception as e:
        raise Exception(f"databook id loading error! {e}")

get_databooks()

Get a list of databook

Parameters

None

Returns

_db : list databook list databook_df : pd.DataFrame databook dataframe databook_json : str databook json

Notes

1. _db is the name of all books (databooks)

Source code in pyThermoDB/manager/managedata.py

def get_databooks(self) -> tuple[list[str], pd.DataFrame, str]:
    '''
    Get a list of databook

    Parameters
    ----------
    None

    Returns
    -------
    _db : list
        databook list
    databook_df : pd.DataFrame
        databook dataframe
    databook_json : str
        databook json

    Notes
    ------
    1. _db is the name of all books (databooks)
    '''
    try:
        # databook list
        _db = list(self.__databook_bulk.keys())
        # add id
        res = [(db, f"[{i+1}]") for i, db in enumerate(_db)]

        # create dict
        databook_dict = {
            f"databook-{i+1}": str(db) for i, db in enumerate(_db)
        }
        # create json
        databook_json = json.dumps(databook_dict, indent=4)

        # dataframe
        # column name
        column_name = "Databooks"
        databook_df = pd.DataFrame(res, columns=[column_name, "Id"])
        # return
        return _db, databook_df, databook_json

    except Exception as e:
        raise Exception(f"databook loading error! {e}")

get_descriptions()

Get databook descriptions

Source code in pyThermoDB/manager/managedata.py

def get_descriptions(self) -> tuple[dict, list, str, pd.DataFrame]:
    '''
    Get databook descriptions
    '''
    try:
        # dict
        res = self.__description
        # list
        res_list = [(value, key) for key, value in res.items()]
        # json
        res_json = json.dumps(res, indent=4)
        # dataframe
        res_df = pd.DataFrame(res_list, columns=['Tables', 'Descriptions'])

        # res
        return res, res_list, res_json, res_df
    except Exception as e:
        raise Exception(f"description loading error! {e}")

get_descriptions_by_databook(databook)

Get descriptions by databook

Parameters

databook : str databook name

Returns

descriptions : dict descriptions of the databook

Source code in pyThermoDB/manager/managedata.py

def get_descriptions_by_databook(self, databook: str) -> dict:
    '''
    Get descriptions by databook

    Parameters
    ----------
    databook : str
        databook name

    Returns
    -------
    descriptions : dict
        descriptions of the databook
    '''
    try:
        # check
        if databook not in self.__description:
            raise ValueError(f"Databook {databook} not found!")

        # get descriptions
        descriptions = self.__description[databook]

        # return
        return descriptions
    except Exception as e:
        raise Exception(f"description loading error! {e}")

get_symbols()

Get symbols

Parameters

None

Returns

symbols : dict symbols

Source code in pyThermoDB/manager/managedata.py

def get_symbols(self) -> tuple[dict, list, str, pd.DataFrame]:
    '''
    Get symbols

    Parameters
    ----------
    None

    Returns
    -------
    symbols : dict
        symbols
    '''
    try:
        # dict
        res = self.symbols['SYMBOLS']
        # list
        res_list = [(value, key) for key, value in res.items()]
        # json
        res_json = json.dumps(res, indent=4)
        # dataframe
        res_df = pd.DataFrame(res_list, columns=['Symbol', 'Description'])

        # res
        return res, res_list, res_json, res_df

    except Exception as e:
        raise Exception(f"symbol loading error! {e}")

get_table(databook, table)

Get a table with respect to databook and table id or name

Parameters

databook : str | int | list databook name or id (zero-based id) table : int table id (zero-based id) or name

Returns

table : DataBookTableTypes selected table based on databook and table id or name

Source code in pyThermoDB/manager/managedata.py

def get_table(self,
              databook: str | int | list[DataBookTableTypes],
              table: int | str) -> DataBookTableTypes:
    '''
    Get a table with respect to databook and table id or name

    Parameters
    ----------
    databook : str | int | list
        databook name or id (zero-based id)
    table : int
        table id (zero-based id) or name

    Returns
    -------
    table : DataBookTableTypes
        selected table based on databook and table id or name
    '''
    try:
        # select databook
        if isinstance(databook, str):
            databook_set = self.databook_bulk[databook]
        elif isinstance(databook, int):
            databook_set = self.databook_bulk[self.__databook[databook]]
        else:
            # for previously extracted databook
            databook_set = databook

        # ! if databook list
        # list
        # selected_tb: DataBookTableTypes
        selected_tb = None

        # SECTION: set table type
        def set_table_type(tb):
            # check table type
            if 'equations' in tb and tb['equations'] is not None:
                return TableTypes.EQUATIONS.value
            elif 'data' in tb and tb['data'] is not None:
                return TableTypes.DATA.value
            elif 'matrix_data' in tb and tb['matrix_data'] is not None:
                return TableTypes.MATRIX_DATA.value
            elif 'matrix_equations' in tb and tb['matrix_equations'] is not None:
                return TableTypes.MATRIX_EQUATIONS.value
            else:
                raise Exception("table type unknown!")

        # by table id
        if isinstance(table, int):
            # check table and equations
            for i, tb in enumerate(databook_set):
                # check table id
                if i == table:
                    selected_tb = DataBookTableTypes(**tb)
                    # NOTE: check table type
                    # tb_name_ = selected_tb['table']
                    # set
                    selected_tb['table_type'] = set_table_type(tb)
                    break
        # by table name
        elif isinstance(table, str):
            # check table name
            for i, tb in enumerate(databook_set):
                # check table name
                if tb['table'] == table:
                    selected_tb = DataBookTableTypes(**tb)
                    # NOTE: check table type
                    # tb_name_ = selected_tb['table']
                    # set
                    selected_tb['table_type'] = set_table_type(tb)
                    break
        else:
            raise Exception("Invalid table type")

        # NOTE: check selected table
        if selected_tb is None:
            raise Exception("table not found!")
        # return
        return selected_tb
    except Exception as e:
        raise Exception(f"table loading err! {e}")

get_table_id(databook, table, res_format='json')

Get table id

Parameters

databook : str | int databook name or id table : str table name

Returns

table_id : str | dict[str, str] table id

Source code in pyThermoDB/manager/managedata.py

def get_table_id(self,
                 databook: str | int,
                 table: str,
                 res_format: Literal[
                     'str', 'json', 'dict'
                 ] = 'json') -> str | dict[str, str]:
    '''
    Get table id

    Parameters
    ----------
    databook : str | int
        databook name or id
    table : str
        table name

    Returns
    -------
    table_id : str | dict[str, str]
        table id
    '''
    try:
        # select databook
        if isinstance(databook, str):
            databook_set = self.databook_bulk[databook]
        elif isinstance(databook, int):
            databook_set = self.databook_bulk[self.__databook[databook]]
        else:
            raise ValueError("databook must be str or int!")

        # table id
        table_id = 'Table id not found!'

        # check table and equations
        for i, tb in enumerate(databook_set):
            # check table id
            if tb['table'] == table:
                table_id = str(i+1)
                break

        # check
        if res_format == 'str':
            return table_id
        elif res_format == 'json':
            return json.dumps({"table_id": table_id}, indent=4)
        elif res_format == 'dict':
            return {"table_id": table_id}
        else:
            raise ValueError("res_format must be 'str' or 'json'!")

    except Exception as e:
        raise Exception(f"table id loading err! {e}")

get_table_type(databook, table_id)

Get a table type

Parameters

databook : int databook id (non-zero-based) table_id : int table id (non-zero-based)

Returns

table_type : str table type

Source code in pyThermoDB/manager/managedata.py

def get_table_type(self, databook: int, table_id: int) -> str:
    '''
    Get a table type

    Parameters
    ----------
    databook : int
        databook id (non-zero-based)
    table_id : int
        table id (non-zero-based)

    Returns
    -------
    table_type : str
        table type
    '''
    try:
        # get table
        tb = self.get_table(databook-1, table_id-1)

        # filter
        filter_keys = [enum.value for enum in TableTypes]

        # table data type
        tb_bulk = {key: value for key, value in tb.items(
        ) if key in filter_keys and value is not None}

        # table type
        tb_type = ''

        # check
        if len(tb_bulk) == 1:
            tb_type, _ = tb_bulk.popitem()
        else:
            raise Exception("table type unknown!")

        # return
        return tb_type

    except Exception as e:
        raise Exception(f"table info loading err! {e}")

get_table_values(databook, table)

Get table values

Parameters

databook : str | int databook name or id table : str | int table name or id

Returns

table_values : list table values

Source code in pyThermoDB/manager/managedata.py

def get_table_values(self, databook: str | int, table: str | int):
    '''
    Get table values

    Parameters
    ----------
    databook : str | int
        databook name or id
    table : str | int
        table name or id

    Returns
    -------
    table_values : list
        table values
    '''
    try:
        # NOTE: find databook
        db, db_name, db_id = self.find_databook(databook)

        # NOTE: find table
        tb_id, tb_name = self.find_table(db_name, table)

        # NOTE: get table
        tb = self.get_table(db_name, tb_name)

        return tb

    except Exception as e:
        raise Exception(f"table values loading err! {e}")

get_tables(databook)

Get a table list of selected databook

Parameters

databook : str databook name

Returns

tables : list | pandas.DataFrame | str table list of selected databook

Source code in pyThermoDB/manager/managedata.py

def get_tables(
        self,
        databook
) -> tuple[list[list[str]], pd.DataFrame, str, dict[str, str]]:
    '''
    Get a table list of selected databook

    Parameters
    ----------
    databook : str
        databook name

    Returns
    -------
    tables : list | pandas.DataFrame | str
        table list of selected databook
    '''
    try:
        # list tables
        if isinstance(databook, str):
            _dbs = self.__databook_bulk[databook]
        elif isinstance(databook, int):
            _dbs = self.__databook_bulk[self.__databook[databook]]
        # list
        tables: list[list[str]] = []
        # check table and equations
        for i, tb in enumerate(_dbs):
            # check
            # ! equation
            if tb['equations'] is not None:
                tables.append([tb['table'], "equation",
                              f"[{i+1}]"])
            # ! data
            elif tb['data'] is not None:
                tables.append([tb['table'], "data", f"[{i+1}]"])
            # ! matrix-data
            elif tb['matrix_data'] is not None:
                tables.append(
                    [tb['table'], "matrix-data", f"[{i+1}]"])
            # ! matrix-equation
            elif tb['matrix_equations'] is not None:
                tables.append(
                    [tb['table'], "matrix-equation", f"[{i+1}]"])
            else:
                raise Exception("data type unknown!")

        # dataframe
        # column name
        column_name = f"Tables in {databook} databook"

        # convert to json
        tables_dict = {f"table-{i+1}": tb[0]
                       for i, tb in enumerate(tables)}
        # convert to json
        tables_json = json.dumps(tables_dict, indent=4)

        # ! set table dataframe
        tables_df = pd.DataFrame(
            tables, columns=[column_name, "Type", "Id"])
        # return
        return tables, tables_df, tables_json, tables_dict
    except Exception as e:
        raise Exception(f"table loading err! {e}")

load_custom_reference(custom_ref, save_to_file=False, file_format='txt', file_name=None, output_dir=None) staticmethod

Load custom reference data from file

Parameters

custom_ref : CustomRef | None custom reference object save_to_file : bool, optional If True, save the custom reference to a txt file, by default False file_format : Literal['txt', 'yml'], optional Format of the file to save the custom reference, by default 'txt'. Options are 'txt' or 'yml'. file_name : str, optional Name of the file to save the custom reference, by default None. output_dir : str, optional Directory to save the custom reference file, by default None.

Returns

dict[str, dict] custom reference data

Source code in pyThermoDB/manager/managedata.py

@staticmethod
def load_custom_reference(
    custom_ref: CustomRef,
    save_to_file: bool = False,
    file_format: Literal['txt', 'yml'] = 'txt',
    file_name: Optional[str] = None,
    output_dir: Optional[str] = None
) -> Dict[str, Any] | None:
    '''
    Load custom reference data from file

    Parameters
    ----------
    custom_ref : CustomRef | None
        custom reference object
    save_to_file : bool, optional
        If True, save the custom reference to a txt file, by default False
    file_format : Literal['txt', 'yml'], optional
        Format of the file to save the custom reference, by default 'txt'. Options are 'txt' or 'yml'.
    file_name : str, optional
        Name of the file to save the custom reference, by default None.
    output_dir : str, optional
        Directory to save the custom reference file, by default None.

    Returns
    -------
    dict[str, dict]
        custom reference data
    '''
    try:
        # NOTE: check custom_ref
        if not isinstance(custom_ref, CustomRef):
            logging.warning("Custom reference is not provided or invalid!")
            return {}

        # NOTE: load custom reference
        if custom_ref:
            # check if directory is provided
            if output_dir is None:
                # use current working directory
                output_dir = os.getcwd()

            # check if directory exists
            if not os.path.exists(output_dir):
                # create directory
                os.makedirs(output_dir)

            # SECTION: load custom reference
            ref = custom_ref.load_ref()

            # check if ref is empty
            if not ref:
                logging.warning("Custom reference is empty!")
                return {}

            # check if file_name is provided
            if file_name is None:
                # use default file name
                if file_format == 'txt':
                    file_name = "custom_reference.txt"
                elif file_format == 'yml':
                    file_name = "custom_reference.yml"
                else:
                    logging.warning(
                        "Invalid file format! Use 'txt' or 'yml'.")
                    return {}
            else:
                # set name
                file_name = file_name.strip() + f".{file_format}"

            if save_to_file:
                # build the full file path using directory and file_name
                file_path = os.path.join(output_dir, file_name)

                # check file format
                if file_format == 'txt':
                    # ! to txt file
                    with open(file_path, "w") as f:
                        # `indent=4` for nice formatting
                        json.dump(ref, f, indent=4)
                elif file_format == 'yml':
                    # ! to yaml file
                    with open(file_path, "w") as f:
                        # `default_flow_style=False` for nice formatting
                        yaml.dump(ref, f, sort_keys=False)
                else:
                    logging.warning(
                        "Invalid file format! Use 'txt' or 'yml'.")

            return ref
        else:
            return {}
    except Exception as e:
        logging.error(f"Error loading custom reference: {e}")
        return {}

load_descriptions()

Load reference descriptions for databooks

Source code in pyThermoDB/manager/managedata.py

def load_descriptions(self):
    """
    Load reference descriptions for databooks
    """
    try:
        # references
        references = self.__reference['REFERENCES']

        # descriptions
        descriptions = {}

        for key, value in references.items():
            # databook name
            databook_name = key
            # databook id
            DATABOOK_ID = value.get('DATABOOK-ID', None)

            # init
            descriptions[databook_name] = {}
            # set
            descriptions[databook_name]['DATABOOK-ID'] = DATABOOK_ID

            # check tables
            for table, table_data in value.get('TABLES', {}).items():
                # check
                if 'DESCRIPTION' in table_data:
                    descriptions[databook_name][table] = {
                        'DATABOOK-ID': DATABOOK_ID,
                        'TABLE-ID': table_data.get('TABLE-ID', None),
                        'DESCRIPTION': table_data['DESCRIPTION']
                    }
                else:
                    descriptions[databook_name][table] = {
                        'DATABOOK-ID': DATABOOK_ID,
                        'TABLE-ID': table_data.get('TABLE-ID', None),
                        'DESCRIPTION': None
                    }

        # return
        return descriptions
    except Exception as e:
        raise Exception(f"load_descriptions error! {e}")

load_reference(custom_ref)

load reference data from file

Parameters

custom_ref : str custom reference file path to reference file

Returns

reference : dict reference data

Source code in pyThermoDB/manager/managedata.py

def load_reference(self, custom_ref: CustomRef | None) -> dict[str, dict]:
    '''
    load reference data from file

    Parameters
    ----------
    custom_ref : str
        custom reference file path to reference file

    Returns
    -------
    reference : dict
        reference data
    '''
    # current dir
    current_path = os.path.join(os.path.dirname(__file__))

    # Go back to the parent directory (pyThermoDB)
    parent_path = os.path.abspath(os.path.join(current_path, '..'))

    # Now navigate to the data folder
    data_path = os.path.join(parent_path, 'config')

    # relative
    config_path = os.path.join(data_path, 'reference.yml')

    with open(config_path, 'r') as f:
        reference = yaml.load(f, Loader=yaml.FullLoader)

    # update reference local
    self.__reference_local_no = len(reference['REFERENCES'])

    # check custom reference
    if custom_ref:
        # get data
        custom_reference = custom_ref.load_ref()
        # merge data
        reference['REFERENCES'].update(custom_reference)

    # log
    # <class 'dict'>
    # print(type(reference))
    return reference

load_symbols(custom_ref)

Load symbols used in the databooks

Parameters

None

Returns

symbols : list list of symbols

Source code in pyThermoDB/manager/managedata.py

def load_symbols(self, custom_ref: CustomRef | None) -> dict:
    '''
    Load symbols used in the databooks

    Parameters
    ----------
    None

    Returns
    -------
    symbols : list
        list of symbols
    '''
    try:
        # current dir
        current_path = os.path.join(os.path.dirname(__file__))

        # Go back to the parent directory (pyThermoDB)
        parent_path = os.path.abspath(os.path.join(current_path, '..'))

        # Now navigate to the data folder
        data_path = os.path.join(parent_path, 'config')

        # relative
        config_path = os.path.join(data_path, 'symbols.yml')

        with open(config_path, 'r') as f:
            symbols = yaml.load(f, Loader=yaml.FullLoader)

        # check custom symbols
        if custom_ref:
            # get data
            custom_symbols = custom_ref.load_symbols()
            # check
            if len(custom_symbols) > 0:
                # merge data
                symbols['SYMBOLS'].update(custom_symbols)

        # return
        return symbols
    except Exception as e:
        raise Exception(f"symbol loading error! {e}")

select_reference(reference)

Select a reference from the loaded references

Parameters

reference : str reference name

Source code in pyThermoDB/manager/managedata.py

def select_reference(self, reference: str) -> dict:
    '''
    Select a reference from the loaded references

    Parameters
    ----------
    reference : str
        reference name

    '''
    try:
        # check
        if reference not in self.__reference['REFERENCES']:
            raise ValueError(f"Reference {reference} not found!")

        # get reference
        selected_ref = self.__reference['REFERENCES'][reference]

        # return
        return selected_ref
    except Exception as e:
        raise Exception(f"select reference error! {e}")

customref

CustomRef

Manage new custom references

Source code in pyThermoDB/loader/customref.py

class CustomRef:
    '''
    Manage new custom references
    '''

    def __init__(self, ref):
        self.ref = ref

        # NOTE: files
        self.src_files: list[str] = []
        self.yml_files: list[str] = []
        self.csv_files: list[str] = []
        self.md_files: list[str] = []

        # NOTE: raw content
        self.contents: List[str | dict] | None = None

        # NOTE: paths
        self.yml_paths: list[str] = []
        self.csv_paths: list[str] = []
        self.md_paths: list[str] = []

        # NOTE: symbols
        self.symbols_files: list[str] = []
        self.symbols_paths: list[str] = []

        # NOTE: data mode
        self.data_mode: Literal['NORMAL', 'VALUES'] = self.set_data_mode()

    def set_data_mode(
        self
    ):
        '''
        Set data mode

        Returns
        -------
        data_mode : str
            data mode, 'NORMAL' or 'VALUES'
        '''
        try:
            # ref keys
            ref_keys = list(self.ref.keys())
            ref_keys = [x.lower() for x in ref_keys]

            # check ref keys [yml, reference, csv, tables, symbols]
            if len(ref_keys) == 0:
                logging.warning("No reference keys found.")
                raise RuntimeError("No reference keys found.")

            # NOTE: check data mode
            # ! only one key is allowed
            if len(ref_keys) == 1:
                # yml or reference
                if 'yml' in ref_keys or 'reference' in ref_keys:
                    # set data mode
                    return 'VALUES'

            # res
            return 'NORMAL'
        except Exception as e:
            raise RuntimeError(f"Setting data mode failed! {e}")

    def init_ref(self) -> bool:
        '''
        Update reference through updating yml

        Parameters
        ----------
        data_mode : str, optional
            data mode, by default 'NORMAL'

        Notes
        ----------
        yml_files : list
            yml files
        csv_files : list
            csv files

        Returns
        -------
        bool
            True if reference is updated, False otherwise
        '''
        try:
            # REVIEW: deprecated reference keys
            if 'yml' in self.ref.keys() or 'md' in self.ref.keys():
                logger.warning(
                    "'yml' key is deprecated, please use 'reference' instead.")

            # SECTION: extract data
            # NOTE: reference
            src_files = self.ref.get('yml') or self.ref.get('md')

            # check
            if src_files is None:
                src_files = self.ref.get(
                    'reference') or self.ref.get('references')
            # check
            if src_files is None:
                raise Exception("No reference files found.")
            # set
            self.src_files = src_files
            # check type
            if not isinstance(src_files, list):
                raise Exception("Reference files must be a list.")
            if len(src_files) == 0:
                raise Exception("No reference files found.")

            # NOTE: tables
            csv_files = self.ref.get('csv') or self.ref.get('tables', [])
            # NOTE: symbols (optional)
            symbol_files = self.ref.get('symbols') or []

            # SECTION: check files exist
            # NOTE: csv files only for NORMAL mode (yml + csv)
            # NOTE: for VALUES mode (yml/md or string content), no csv files are needed
            if len(csv_files) == 0 and self.data_mode == 'NORMAL':
                raise Exception("No csv files to update.")

            # SECTION: extract files from source files
            # NOTE: check file types
            # ! yml files
            yml_files = [x for x in self.src_files if str(x).endswith('.yml')]
            # ! md files
            md_files = [x for x in self.src_files if str(x).endswith('.md')]

            # SECTION: check string format
            # NOTE: if no yml/md files, check content
            # ! only for VALUES mode
            if len(yml_files) == 0 and len(md_files) == 0:
                # get content
                contents_ = self.ref.get('reference')
                # std content
                if isinstance(contents_, list):
                    # check
                    self.contents = self.content_manager(contents_)

            # SECTION: check file path
            # NOTE: yml files
            if len(yml_files) > 0:
                for yml_file in yml_files:
                    if not os.path.exists(yml_file):
                        raise Exception(f"{yml_file} does not exist.")
                    else:
                        # check file ext
                        if yml_file.endswith('.yml'):
                            # get path
                            self.yml_paths.append(os.path.abspath(yml_file))

            # NOTE: md files
            if len(md_files) > 0:
                for md_file in md_files:
                    if not os.path.exists(md_file):
                        raise Exception(f"{md_file} does not exist.")
                    else:
                        # check file ext
                        if md_file.endswith('.md'):
                            # get path
                            self.md_paths.append(os.path.abspath(md_file))

            # SECTION: check
            if self.data_mode == 'NORMAL':
                for csv_file in csv_files:
                    if not os.path.exists(csv_file):
                        raise Exception(f"{csv_file} does not exist.")
                    else:
                        # get path
                        self.csv_paths.append(os.path.abspath(csv_file))

            # NOTE: update vars
            # yml files
            self.yml_files = yml_files
            # md files
            self.md_files = md_files

            # NOTE: check
            if self.data_mode == 'NORMAL':
                self.csv_files = csv_files

            # SECTION: check
            if len(symbol_files) > 0:
                # symbols
                for symbol_file in symbol_files:
                    if not os.path.exists(symbol_file):
                        raise Exception(f"{symbol_file} does not exist.")
                    else:
                        # get path
                        self.symbols_paths.append(os.path.abspath(symbol_file))

                # update vars
                self.symbols_files = symbol_files

            return True
        except Exception as e:
            logger.error(f"updating reference failed! {e}")
            return False

    def load_ref(self) -> dict:
        '''
        Load reference

        Returns
        -------
        ref : dict
            reference
        '''
        try:
            # data
            data = {}

            # SECTION: check yml files
            if len(self.yml_files) > 0:
                # loop through the rest of the files
                for i in range(0, len(self.yml_files)):
                    with open(self.yml_files[i], 'r') as f:
                        # load data
                        temp_data = yaml.load(f, Loader=yaml.FullLoader)
                        # check
                        if temp_data is None:
                            raise Exception(
                                "No data in the file number %d" % i)
                        # merge data
                        data.update(temp_data['REFERENCES'])

            # SECTION: check md files
            if len(self.md_files) > 0:
                # loop through the rest of the files
                for i in range(0, len(self.md_files)):
                    with open(self.md_files[i], 'r', encoding='utf-8') as f:
                        # load data
                        content = f.read()
                        # check
                        if content is None:
                            raise Exception(
                                "No data in the file number %d" % i)

                        # extract data
                        temp_data = self.parse_markdown(content)
                        # merge data
                        data.update(temp_data['REFERENCES'])

            # SECTION: check content
            if self.contents is not None and len(self.contents) > 0:
                # loop through the rest of the files
                for i in range(0, len(self.contents)):
                    # load data
                    content = self.contents[i]
                    # check
                    if content is None:
                        raise Exception(
                            "No data in the file number %d" % i)

                    # NOTE: check if content is a dict
                    if isinstance(content, dict):
                        # ! dict
                        # extract data
                        temp_data = content
                    else:
                        # ! str
                        # ? check content format
                        content_format = self.check_content_format(content)

                        # NOTE: extract data
                        if content_format == 'yml':
                            # ! yml
                            # load data
                            temp_data = yaml.load(
                                content,
                                Loader=yaml.FullLoader
                            )

                            # check
                            if temp_data is None:
                                raise Exception(
                                    "No data in the content number %d" % i)

                        elif content_format == 'markdown':
                            # ! markdown
                            # parse markdown
                            temp_data = self.parse_markdown(content)
                        else:
                            raise Exception(
                                f"Content format {content_format} not recognized.")

                    # NOTE: merge data
                    data.update(temp_data['REFERENCES'])

            # res
            return data
        except Exception as e:
            raise Exception(f"loading reference failed! {e}")

    def load_symbols(self) -> dict:
        '''
        Load symbols

        Returns
        -------
        symbols : dict
            symbols
        '''
        try:
            # data
            data = {}

            # check
            if self.symbols_files is not None:
                # loop through the rest of the files
                for i in range(0, len(self.symbols_files)):
                    with open(self.symbols_files[i], 'r') as f:
                        # load data
                        temp_data = yaml.load(f, Loader=yaml.FullLoader)
                        # check
                        if temp_data is None:
                            raise Exception(
                                "No data in the file number %d" % i)
                        # merge data
                        data.update(temp_data['SYMBOLS'])

            # res
            return data
        except Exception as e:
            raise Exception(f"loading symbols failed! {e}")

    def parse_markdown(self, content: str) -> dict:
        """
        Parse a structured markdown content and extract information.

        Parameters
        ----------
        content : str
            The markdown content to parse.

        Returns
        -------
        dict
            Dictionary containing all the extracted information.
        """
        try:
            # Initialize the result dictionary
            databook_data = {}
            result = {}

            # databook name
            databook_name_match = re.findall(r'## (.*?)(?:\n|$)', content)
            if databook_name_match:
                databook_name_ = databook_name_match[0].strip()
                databook_data[databook_name_] = {}

            # Extract DATABOOK-ID
            databook_match = re.search(r'DATABOOK-ID: (.*?)(?:\n|$)', content)
            if databook_match:
                result['DATABOOK-ID'] = databook_match.group(1).strip()

            # Find all tables through ### table-name
            table_matches = re.findall(r'### (.*?)(?:\n|$)', content)
            if table_matches:
                result['TABLES'] = {}
                for i, table_name in enumerate(table_matches):
                    # Determine the start and end of the table content
                    start_pattern = rf'### {table_name}.*?\n'
                    if i + 1 < len(table_matches):
                        end_pattern = rf'### {table_matches[i + 1]}'
                    else:
                        end_pattern = r'\Z'

                    table_content_match = re.search(
                        rf'{start_pattern}(.*?)(?={end_pattern})',
                        content,
                        re.DOTALL
                    )

                    if table_content_match:
                        table_data = self.parse_markdown_table(
                            table_content_match.group(0))
                        # result['TABLES'].append({table_name: table_data})
                        result['TABLES'][table_name] = table_data

            # update
            databook_data[databook_name_].update(result)
            # reference
            reference = {'REFERENCES': databook_data}

            return reference
        except Exception as e:
            raise Exception(f"Parsing markdown failed! {e}")

    def parse_markdown_table(self, content: str):
        """
        Parse a structured markdown content and extract information.

        Parameters
        ----------
        content : str
            The markdown content to parse.

        Returns
        -------
        dict
            Dictionary containing all the extracted information.
        """
        # Initialize the result dictionary
        result = {}

        # SECTION: TABLE-ID
        table_match = re.search(r'TABLE-ID: (.*?)(?:\n|$)', content)
        if table_match:
            result['TABLE-ID'] = table_match.group(1).strip()

        # SECTION: DESCRIPTION
        desc_match = re.search(r'DESCRIPTION: (.*?)(?:\n|$)', content)
        if desc_match:
            result['DESCRIPTION'] = desc_match.group(1).strip()

        # SECTION: DATA
        data_match = re.search(r'DATA: \[(.*?)\]', content, re.DOTALL)
        if data_match:
            data_str = data_match.group(1).strip()
            if data_str:
                try:
                    result['DATA'] = ast.literal_eval(f"[{data_str}]")
                except Exception:
                    result['DATA'] = data_str
            else:
                result['DATA'] = []

        # Extract MATRIX-SYMBOL
        matrix_match = re.search(
            r'MATRIX-SYMBOL:\s*\n(.*?)(?:\n\w+:|$)', content, re.DOTALL
        )
        if matrix_match:
            matrix_content = matrix_match.group(1).strip()
            matrix_items = re.findall(r'- (.*?)(?:\n|$)', matrix_content)
            result['MATRIX-SYMBOL'] = [item.strip() for item in matrix_items]

        # SECTION: EQUATIONS
        equations = {}
        eq_pattern = r'EQUATIONS:\s*\n(.*?)(?:\n\w+:|$)'
        eq_section = re.search(eq_pattern, content, re.DOTALL)
        if eq_section:
            eq_content = eq_section.group(1)
            eq_pattern = r'- (EQ-\d+):\s*\n(.*?)(?=\n- EQ-\d+:|\n\w+:|$)'
            eq_blocks = re.findall(eq_pattern, eq_content, re.DOTALL)

            # Debug output to verify equation blocks found
            # print(f"Found {len(eq_blocks)} equation blocks")

            for eq_id, eq_block in eq_blocks:
                equation = {}

                # Extract parts like BODY, BODY-INTEGRAL, etc.
                parts_pattern = (
                    r'  - (\w+(?:-\w+)*):\s*\n(.*?)(?=  - \w+(?:-\w+)*:|\Z)'
                )
                parts = re.findall(parts_pattern, eq_block + '  - ', re.DOTALL)

                for part_name, part_content in parts:
                    # Extract content items from the part content
                    content_items = re.findall(
                        r'- (.*?)(?:\n|$)', part_content)
                    if content_items:
                        equation[part_name] = [
                            item.strip().rstrip('-').strip()
                            for item in content_items
                        ]
                    else:
                        # Ensure empty lists for missing content
                        equation[part_name] = 'None'

                equations[eq_id] = equation

            result['EQUATIONS'] = equations

        # SECTION: STRUCTURE
        structure = {}
        struct_pattern = r'STRUCTURE:\s*\n(.*?)(?:\n\w+:|$)'
        struct_section = re.search(struct_pattern, content, re.DOTALL)
        if struct_section:
            struct_content = struct_section.group(1)

            # Extract parts like COLUMNS, SYMBOL, etc.
            struct_parts = re.findall(r'- (\w+):\s*\[(.*?)\]', struct_content)

            for part_name, part_content in struct_parts:
                try:
                    items = [item.strip() for item in part_content.split(',')]
                    structure[part_name] = items
                except Exception:
                    structure[part_name] = part_content

            result['STRUCTURE'] = structure

        # SECTION: VALUES
        values = []
        values_pattern = r'VALUES:\s*\n(.*?)(?:\n\w+:|$)'
        values_section = re.search(values_pattern, content, re.DOTALL)
        if values_section:
            values_content = values_section.group(1)
            value_rows = re.findall(r'- \[(.*?)\]', values_content)

            for row in value_rows:
                # NOTE: replace double quotes with single quotes
                # row = row.replace('"', "'")
                # NOTE: remove quotes from left and right
                row = row.strip().strip('"')
                # NOTE: remove quotes from left and right
                row = row.strip().strip("'")

                try:
                    # Use a regex to split on commas but not on commas inside single or double quotes
                    items = []
                    # Split by commas that are not within single or
                    # double quotes
                    # pattern = r',\s*(?=(?:[^\'"]*(\'|")[^\'"]*\1)*[^\']*$)'
                    pattern = r"""
                        (                             # Capture group
                            "(?:[^"\\]|\\.)*"         # Double-quoted string, allowing escaped quotes
                            |                         # OR
                            '(?:[^'\\]|\\.)*'         # Single-quoted string, allowing escaped quotes
                            |                         # OR
                            [^,\[\]\s]+               # Unquoted tokens (numbers, identifiers)
                        )
                    """

                    # split the row
                    # parts = re.split(pattern, row)
                    parts = re.findall(pattern, row, re.VERBOSE)

                    # loop through the parts
                    for part in parts:
                        # remove quotes from left and right
                        part = part.strip().strip('"').strip("'")
                        # check if part is empty
                        if part == '':
                            continue

                        items.append(part)
                    values.append(items)
                except Exception:
                    values.append(row)

            result['VALUES'] = values

        # SECTION: ITEMS
        items_match = re.search(
            r'ITEMS:\s*\n(.*?)(?:\n\w+:|$)', content, re.DOTALL
        )
        if items_match:
            items_content = items_match.group(1).strip()
            items = []
            # Updated regex to capture all elements starting with - item:
            item_pattern = (
                # Match any item names starting with "- "
                r'- ([\|\w\d\s]+):\s*\n'
                # Match content containing list elements with square brackets
                r'((?:\s*- \[.*?\]\s*\n)+)'
            )
            item_blocks = re.findall(
                item_pattern,
                items_content,
                re.DOTALL
            )

            for item_name, item_content in item_blocks:
                item_values = re.findall(r'- \[(.*?)\]', item_content)
                _item_res = [
                    [value.strip() for value in row.split(',')]
                    for row in item_values
                ]

                # item name
                item_name = str(item_name).strip()

                # append
                items.append({
                    item_name: _item_res
                })

            result['ITEMS'] = items

        # SECTION: EXTERNAL-REFERENCES
        external_references = []
        ext_ref_pattern = r'EXTERNAL-REFERENCES:\s*\n(.*?)(?:\n\w+:|$)'
        ext_ref_section = re.search(ext_ref_pattern, content, re.DOTALL)
        if ext_ref_section:
            ext_ref_content = ext_ref_section.group(1)
            external_references = re.findall(
                r'- (.*?)(?:\n|$)', ext_ref_content)

            result['EXTERNAL-REFERENCES'] = [
                ref.strip() for ref in external_references
            ]

        return result

    def content_manager(
            self,
            content: List[str | dict]
    ) -> List[str | dict]:
        '''
        Manage content

        Parameters
        ----------
        content : List[str]
            list of content containing separate references

        Returns
        -------
        content : str | dict
            content
        '''
        try:
            # NOTE: check content
            if content is None:
                raise Exception("No content found.")

            # length check
            if len(content) == 0:
                raise Exception("No content found.")

            return content
        except Exception as e:
            raise Exception(f"Content manager failed! {e}")

    def check_content_format(
            self,
            content: str | dict
    ) -> str:
        """
        Check the format of the content and return markdown or yml.

        Parameters
        ----------
        content : str
            The content to check.

        Returns
        -------
        str
            'markdown' if the content is in markdown format, 'yml' otherwise.
        """
        try:
            # NOTE: If content is a dictionary, convert it to a string
            if isinstance(content, dict):
                return 'dict'

            # NOTE: set content to string
            content = str(content)

            # Regex to match a line starting with optional spaces, then # REFERENCES
            pattern = r"^\s*#\s*REFERENCES\s*$"

            # check if the content matches the markdown pattern
            if re.search(pattern, content, re.MULTILINE | re.IGNORECASE):
                return 'markdown'
            # Check if the content is in YAML format
            elif yaml.safe_load(content) is not None:
                return 'yml'
            else:
                raise ValueError("Content format not recognized.")
        except Exception as e:
            raise Exception(f"Checking content format failed! {e}")

check_content_format(content)

Check the format of the content and return markdown or yml.

Parameters

content : str The content to check.

Returns

str 'markdown' if the content is in markdown format, 'yml' otherwise.

Source code in pyThermoDB/loader/customref.py

def check_content_format(
        self,
        content: str | dict
) -> str:
    """
    Check the format of the content and return markdown or yml.

    Parameters
    ----------
    content : str
        The content to check.

    Returns
    -------
    str
        'markdown' if the content is in markdown format, 'yml' otherwise.
    """
    try:
        # NOTE: If content is a dictionary, convert it to a string
        if isinstance(content, dict):
            return 'dict'

        # NOTE: set content to string
        content = str(content)

        # Regex to match a line starting with optional spaces, then # REFERENCES
        pattern = r"^\s*#\s*REFERENCES\s*$"

        # check if the content matches the markdown pattern
        if re.search(pattern, content, re.MULTILINE | re.IGNORECASE):
            return 'markdown'
        # Check if the content is in YAML format
        elif yaml.safe_load(content) is not None:
            return 'yml'
        else:
            raise ValueError("Content format not recognized.")
    except Exception as e:
        raise Exception(f"Checking content format failed! {e}")

content_manager(content)

Manage content

Parameters

content : List[str] list of content containing separate references

Returns

content : str | dict content

Source code in pyThermoDB/loader/customref.py

def content_manager(
        self,
        content: List[str | dict]
) -> List[str | dict]:
    '''
    Manage content

    Parameters
    ----------
    content : List[str]
        list of content containing separate references

    Returns
    -------
    content : str | dict
        content
    '''
    try:
        # NOTE: check content
        if content is None:
            raise Exception("No content found.")

        # length check
        if len(content) == 0:
            raise Exception("No content found.")

        return content
    except Exception as e:
        raise Exception(f"Content manager failed! {e}")

init_ref()

Update reference through updating yml

Parameters

data_mode : str, optional data mode, by default 'NORMAL'

Notes

yml_files : list yml files csv_files : list csv files

Returns

bool True if reference is updated, False otherwise

Source code in pyThermoDB/loader/customref.py

def init_ref(self) -> bool:
    '''
    Update reference through updating yml

    Parameters
    ----------
    data_mode : str, optional
        data mode, by default 'NORMAL'

    Notes
    ----------
    yml_files : list
        yml files
    csv_files : list
        csv files

    Returns
    -------
    bool
        True if reference is updated, False otherwise
    '''
    try:
        # REVIEW: deprecated reference keys
        if 'yml' in self.ref.keys() or 'md' in self.ref.keys():
            logger.warning(
                "'yml' key is deprecated, please use 'reference' instead.")

        # SECTION: extract data
        # NOTE: reference
        src_files = self.ref.get('yml') or self.ref.get('md')

        # check
        if src_files is None:
            src_files = self.ref.get(
                'reference') or self.ref.get('references')
        # check
        if src_files is None:
            raise Exception("No reference files found.")
        # set
        self.src_files = src_files
        # check type
        if not isinstance(src_files, list):
            raise Exception("Reference files must be a list.")
        if len(src_files) == 0:
            raise Exception("No reference files found.")

        # NOTE: tables
        csv_files = self.ref.get('csv') or self.ref.get('tables', [])
        # NOTE: symbols (optional)
        symbol_files = self.ref.get('symbols') or []

        # SECTION: check files exist
        # NOTE: csv files only for NORMAL mode (yml + csv)
        # NOTE: for VALUES mode (yml/md or string content), no csv files are needed
        if len(csv_files) == 0 and self.data_mode == 'NORMAL':
            raise Exception("No csv files to update.")

        # SECTION: extract files from source files
        # NOTE: check file types
        # ! yml files
        yml_files = [x for x in self.src_files if str(x).endswith('.yml')]
        # ! md files
        md_files = [x for x in self.src_files if str(x).endswith('.md')]

        # SECTION: check string format
        # NOTE: if no yml/md files, check content
        # ! only for VALUES mode
        if len(yml_files) == 0 and len(md_files) == 0:
            # get content
            contents_ = self.ref.get('reference')
            # std content
            if isinstance(contents_, list):
                # check
                self.contents = self.content_manager(contents_)

        # SECTION: check file path
        # NOTE: yml files
        if len(yml_files) > 0:
            for yml_file in yml_files:
                if not os.path.exists(yml_file):
                    raise Exception(f"{yml_file} does not exist.")
                else:
                    # check file ext
                    if yml_file.endswith('.yml'):
                        # get path
                        self.yml_paths.append(os.path.abspath(yml_file))

        # NOTE: md files
        if len(md_files) > 0:
            for md_file in md_files:
                if not os.path.exists(md_file):
                    raise Exception(f"{md_file} does not exist.")
                else:
                    # check file ext
                    if md_file.endswith('.md'):
                        # get path
                        self.md_paths.append(os.path.abspath(md_file))

        # SECTION: check
        if self.data_mode == 'NORMAL':
            for csv_file in csv_files:
                if not os.path.exists(csv_file):
                    raise Exception(f"{csv_file} does not exist.")
                else:
                    # get path
                    self.csv_paths.append(os.path.abspath(csv_file))

        # NOTE: update vars
        # yml files
        self.yml_files = yml_files
        # md files
        self.md_files = md_files

        # NOTE: check
        if self.data_mode == 'NORMAL':
            self.csv_files = csv_files

        # SECTION: check
        if len(symbol_files) > 0:
            # symbols
            for symbol_file in symbol_files:
                if not os.path.exists(symbol_file):
                    raise Exception(f"{symbol_file} does not exist.")
                else:
                    # get path
                    self.symbols_paths.append(os.path.abspath(symbol_file))

            # update vars
            self.symbols_files = symbol_files

        return True
    except Exception as e:
        logger.error(f"updating reference failed! {e}")
        return False

load_ref()

Load reference

Returns

ref : dict reference

Source code in pyThermoDB/loader/customref.py

def load_ref(self) -> dict:
    '''
    Load reference

    Returns
    -------
    ref : dict
        reference
    '''
    try:
        # data
        data = {}

        # SECTION: check yml files
        if len(self.yml_files) > 0:
            # loop through the rest of the files
            for i in range(0, len(self.yml_files)):
                with open(self.yml_files[i], 'r') as f:
                    # load data
                    temp_data = yaml.load(f, Loader=yaml.FullLoader)
                    # check
                    if temp_data is None:
                        raise Exception(
                            "No data in the file number %d" % i)
                    # merge data
                    data.update(temp_data['REFERENCES'])

        # SECTION: check md files
        if len(self.md_files) > 0:
            # loop through the rest of the files
            for i in range(0, len(self.md_files)):
                with open(self.md_files[i], 'r', encoding='utf-8') as f:
                    # load data
                    content = f.read()
                    # check
                    if content is None:
                        raise Exception(
                            "No data in the file number %d" % i)

                    # extract data
                    temp_data = self.parse_markdown(content)
                    # merge data
                    data.update(temp_data['REFERENCES'])

        # SECTION: check content
        if self.contents is not None and len(self.contents) > 0:
            # loop through the rest of the files
            for i in range(0, len(self.contents)):
                # load data
                content = self.contents[i]
                # check
                if content is None:
                    raise Exception(
                        "No data in the file number %d" % i)

                # NOTE: check if content is a dict
                if isinstance(content, dict):
                    # ! dict
                    # extract data
                    temp_data = content
                else:
                    # ! str
                    # ? check content format
                    content_format = self.check_content_format(content)

                    # NOTE: extract data
                    if content_format == 'yml':
                        # ! yml
                        # load data
                        temp_data = yaml.load(
                            content,
                            Loader=yaml.FullLoader
                        )

                        # check
                        if temp_data is None:
                            raise Exception(
                                "No data in the content number %d" % i)

                    elif content_format == 'markdown':
                        # ! markdown
                        # parse markdown
                        temp_data = self.parse_markdown(content)
                    else:
                        raise Exception(
                            f"Content format {content_format} not recognized.")

                # NOTE: merge data
                data.update(temp_data['REFERENCES'])

        # res
        return data
    except Exception as e:
        raise Exception(f"loading reference failed! {e}")

load_symbols()

Load symbols

Returns

symbols : dict symbols

Source code in pyThermoDB/loader/customref.py

def load_symbols(self) -> dict:
    '''
    Load symbols

    Returns
    -------
    symbols : dict
        symbols
    '''
    try:
        # data
        data = {}

        # check
        if self.symbols_files is not None:
            # loop through the rest of the files
            for i in range(0, len(self.symbols_files)):
                with open(self.symbols_files[i], 'r') as f:
                    # load data
                    temp_data = yaml.load(f, Loader=yaml.FullLoader)
                    # check
                    if temp_data is None:
                        raise Exception(
                            "No data in the file number %d" % i)
                    # merge data
                    data.update(temp_data['SYMBOLS'])

        # res
        return data
    except Exception as e:
        raise Exception(f"loading symbols failed! {e}")

parse_markdown(content)

Parse a structured markdown content and extract information.

Parameters

content : str The markdown content to parse.

Returns

dict Dictionary containing all the extracted information.

Source code in pyThermoDB/loader/customref.py

def parse_markdown(self, content: str) -> dict:
    """
    Parse a structured markdown content and extract information.

    Parameters
    ----------
    content : str
        The markdown content to parse.

    Returns
    -------
    dict
        Dictionary containing all the extracted information.
    """
    try:
        # Initialize the result dictionary
        databook_data = {}
        result = {}

        # databook name
        databook_name_match = re.findall(r'## (.*?)(?:\n|$)', content)
        if databook_name_match:
            databook_name_ = databook_name_match[0].strip()
            databook_data[databook_name_] = {}

        # Extract DATABOOK-ID
        databook_match = re.search(r'DATABOOK-ID: (.*?)(?:\n|$)', content)
        if databook_match:
            result['DATABOOK-ID'] = databook_match.group(1).strip()

        # Find all tables through ### table-name
        table_matches = re.findall(r'### (.*?)(?:\n|$)', content)
        if table_matches:
            result['TABLES'] = {}
            for i, table_name in enumerate(table_matches):
                # Determine the start and end of the table content
                start_pattern = rf'### {table_name}.*?\n'
                if i + 1 < len(table_matches):
                    end_pattern = rf'### {table_matches[i + 1]}'
                else:
                    end_pattern = r'\Z'

                table_content_match = re.search(
                    rf'{start_pattern}(.*?)(?={end_pattern})',
                    content,
                    re.DOTALL
                )

                if table_content_match:
                    table_data = self.parse_markdown_table(
                        table_content_match.group(0))
                    # result['TABLES'].append({table_name: table_data})
                    result['TABLES'][table_name] = table_data

        # update
        databook_data[databook_name_].update(result)
        # reference
        reference = {'REFERENCES': databook_data}

        return reference
    except Exception as e:
        raise Exception(f"Parsing markdown failed! {e}")

parse_markdown_table(content)

Parse a structured markdown content and extract information.

Parameters

content : str The markdown content to parse.

Returns

dict Dictionary containing all the extracted information.

Source code in pyThermoDB/loader/customref.py

def parse_markdown_table(self, content: str):
    """
    Parse a structured markdown content and extract information.

    Parameters
    ----------
    content : str
        The markdown content to parse.

    Returns
    -------
    dict
        Dictionary containing all the extracted information.
    """
    # Initialize the result dictionary
    result = {}

    # SECTION: TABLE-ID
    table_match = re.search(r'TABLE-ID: (.*?)(?:\n|$)', content)
    if table_match:
        result['TABLE-ID'] = table_match.group(1).strip()

    # SECTION: DESCRIPTION
    desc_match = re.search(r'DESCRIPTION: (.*?)(?:\n|$)', content)
    if desc_match:
        result['DESCRIPTION'] = desc_match.group(1).strip()

    # SECTION: DATA
    data_match = re.search(r'DATA: \[(.*?)\]', content, re.DOTALL)
    if data_match:
        data_str = data_match.group(1).strip()
        if data_str:
            try:
                result['DATA'] = ast.literal_eval(f"[{data_str}]")
            except Exception:
                result['DATA'] = data_str
        else:
            result['DATA'] = []

    # Extract MATRIX-SYMBOL
    matrix_match = re.search(
        r'MATRIX-SYMBOL:\s*\n(.*?)(?:\n\w+:|$)', content, re.DOTALL
    )
    if matrix_match:
        matrix_content = matrix_match.group(1).strip()
        matrix_items = re.findall(r'- (.*?)(?:\n|$)', matrix_content)
        result['MATRIX-SYMBOL'] = [item.strip() for item in matrix_items]

    # SECTION: EQUATIONS
    equations = {}
    eq_pattern = r'EQUATIONS:\s*\n(.*?)(?:\n\w+:|$)'
    eq_section = re.search(eq_pattern, content, re.DOTALL)
    if eq_section:
        eq_content = eq_section.group(1)
        eq_pattern = r'- (EQ-\d+):\s*\n(.*?)(?=\n- EQ-\d+:|\n\w+:|$)'
        eq_blocks = re.findall(eq_pattern, eq_content, re.DOTALL)

        # Debug output to verify equation blocks found
        # print(f"Found {len(eq_blocks)} equation blocks")

        for eq_id, eq_block in eq_blocks:
            equation = {}

            # Extract parts like BODY, BODY-INTEGRAL, etc.
            parts_pattern = (
                r'  - (\w+(?:-\w+)*):\s*\n(.*?)(?=  - \w+(?:-\w+)*:|\Z)'
            )
            parts = re.findall(parts_pattern, eq_block + '  - ', re.DOTALL)

            for part_name, part_content in parts:
                # Extract content items from the part content
                content_items = re.findall(
                    r'- (.*?)(?:\n|$)', part_content)
                if content_items:
                    equation[part_name] = [
                        item.strip().rstrip('-').strip()
                        for item in content_items
                    ]
                else:
                    # Ensure empty lists for missing content
                    equation[part_name] = 'None'

            equations[eq_id] = equation

        result['EQUATIONS'] = equations

    # SECTION: STRUCTURE
    structure = {}
    struct_pattern = r'STRUCTURE:\s*\n(.*?)(?:\n\w+:|$)'
    struct_section = re.search(struct_pattern, content, re.DOTALL)
    if struct_section:
        struct_content = struct_section.group(1)

        # Extract parts like COLUMNS, SYMBOL, etc.
        struct_parts = re.findall(r'- (\w+):\s*\[(.*?)\]', struct_content)

        for part_name, part_content in struct_parts:
            try:
                items = [item.strip() for item in part_content.split(',')]
                structure[part_name] = items
            except Exception:
                structure[part_name] = part_content

        result['STRUCTURE'] = structure

    # SECTION: VALUES
    values = []
    values_pattern = r'VALUES:\s*\n(.*?)(?:\n\w+:|$)'
    values_section = re.search(values_pattern, content, re.DOTALL)
    if values_section:
        values_content = values_section.group(1)
        value_rows = re.findall(r'- \[(.*?)\]', values_content)

        for row in value_rows:
            # NOTE: replace double quotes with single quotes
            # row = row.replace('"', "'")
            # NOTE: remove quotes from left and right
            row = row.strip().strip('"')
            # NOTE: remove quotes from left and right
            row = row.strip().strip("'")

            try:
                # Use a regex to split on commas but not on commas inside single or double quotes
                items = []
                # Split by commas that are not within single or
                # double quotes
                # pattern = r',\s*(?=(?:[^\'"]*(\'|")[^\'"]*\1)*[^\']*$)'
                pattern = r"""
                    (                             # Capture group
                        "(?:[^"\\]|\\.)*"         # Double-quoted string, allowing escaped quotes
                        |                         # OR
                        '(?:[^'\\]|\\.)*'         # Single-quoted string, allowing escaped quotes
                        |                         # OR
                        [^,\[\]\s]+               # Unquoted tokens (numbers, identifiers)
                    )
                """

                # split the row
                # parts = re.split(pattern, row)
                parts = re.findall(pattern, row, re.VERBOSE)

                # loop through the parts
                for part in parts:
                    # remove quotes from left and right
                    part = part.strip().strip('"').strip("'")
                    # check if part is empty
                    if part == '':
                        continue

                    items.append(part)
                values.append(items)
            except Exception:
                values.append(row)

        result['VALUES'] = values

    # SECTION: ITEMS
    items_match = re.search(
        r'ITEMS:\s*\n(.*?)(?:\n\w+:|$)', content, re.DOTALL
    )
    if items_match:
        items_content = items_match.group(1).strip()
        items = []
        # Updated regex to capture all elements starting with - item:
        item_pattern = (
            # Match any item names starting with "- "
            r'- ([\|\w\d\s]+):\s*\n'
            # Match content containing list elements with square brackets
            r'((?:\s*- \[.*?\]\s*\n)+)'
        )
        item_blocks = re.findall(
            item_pattern,
            items_content,
            re.DOTALL
        )

        for item_name, item_content in item_blocks:
            item_values = re.findall(r'- \[(.*?)\]', item_content)
            _item_res = [
                [value.strip() for value in row.split(',')]
                for row in item_values
            ]

            # item name
            item_name = str(item_name).strip()

            # append
            items.append({
                item_name: _item_res
            })

        result['ITEMS'] = items

    # SECTION: EXTERNAL-REFERENCES
    external_references = []
    ext_ref_pattern = r'EXTERNAL-REFERENCES:\s*\n(.*?)(?:\n\w+:|$)'
    ext_ref_section = re.search(ext_ref_pattern, content, re.DOTALL)
    if ext_ref_section:
        ext_ref_content = ext_ref_section.group(1)
        external_references = re.findall(
            r'- (.*?)(?:\n|$)', ext_ref_content)

        result['EXTERNAL-REFERENCES'] = [
            ref.strip() for ref in external_references
        ]

    return result

set_data_mode()

Set data mode

Returns

data_mode : str data mode, 'NORMAL' or 'VALUES'

Source code in pyThermoDB/loader/customref.py

def set_data_mode(
    self
):
    '''
    Set data mode

    Returns
    -------
    data_mode : str
        data mode, 'NORMAL' or 'VALUES'
    '''
    try:
        # ref keys
        ref_keys = list(self.ref.keys())
        ref_keys = [x.lower() for x in ref_keys]

        # check ref keys [yml, reference, csv, tables, symbols]
        if len(ref_keys) == 0:
            logging.warning("No reference keys found.")
            raise RuntimeError("No reference keys found.")

        # NOTE: check data mode
        # ! only one key is allowed
        if len(ref_keys) == 1:
            # yml or reference
            if 'yml' in ref_keys or 'reference' in ref_keys:
                # set data mode
                return 'VALUES'

        # res
        return 'NORMAL'
    except Exception as e:
        raise RuntimeError(f"Setting data mode failed! {e}")

compexporter

CompExporter

Source code in pyThermoDB/builder/compexporter.py

class CompExporter:

    # vars
    __properties = {}
    __functions = {}

    def __init__(self):
        self.__functions = {}
        self.__properties = {}
        # allowed types
        # allowed types for properties
        self.allowed_types_properties = (TableData, dict, TableMatrixData)

        # allowed types for equations (functions)
        self.allowed_types_equations = (TableEquation, TableMatrixEquation)

    @property
    def properties(self):
        return self.__properties

    @property
    def functions(self):
        return self.__functions

    def _add(
        self,
        name: str,
        value: TableData | TableEquation | TableMatrixData | TableMatrixEquation
    ):
        '''
        Add a new property/functions

        Parameters
        ----------
        name : str
            name of the property/function
        value : TableData | TableEquation | TableMatrixData | TableMatrixEquation
            value of the property/function

        Returns
        -------
        res : bool
            True if success

        '''
        try:
            # check value
            if value is None:
                raise Exception("Value is required")

            # allowed types for properties
            # _allowed_types_properties = (TableData, dict, TableMatrixData)

            # allowed types for equations (functions)
            # _allowed_types_equations = (TableEquation, TableMatrixEquation)

            # check TableData | TableEquation
            if isinstance(value, self.allowed_types_properties):
                self.__properties[name] = value
            elif isinstance(value, self.allowed_types_equations):
                self.__functions[name] = value
            else:
                raise Exception("Value must be TableData or TableEquation")

            return True
        except Exception as e:
            logger.error(f"Adding a new property failed!, {e}")
            return False

    def _remove(self, name: str) -> bool:
        '''
        Remove a property/functions

        Parameters
        ----------
        name : str
            name of the property/function

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # check
            if name in self.__properties:
                del self.__properties[name]
                return True
            elif name in self.__functions:
                del self.__functions[name]
                return True
            else:
                logger.warning(f"{name} not found!")
                return False
        except Exception as e:
            logger.error(f"Removing a property failed!, {e}")
            return False

    def _update(
            self,
            name: str,
            value: TableData | TableEquation | TableMatrixData | TableMatrixEquation
    ):
        '''
        Update a property/functions

        Parameters
        ----------
        name : str
            name of the property/function
        value : TableData | TableEquation | TableMatrixData | TableMatrixEquation
            value of the property/function

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # check TableData and TableMatrixData
            if isinstance(value, self.allowed_types_properties):
                if name in self.__properties:
                    self.__properties[name] = value
                    return True
                else:
                    logger.warning(f"{name} not found!")
                    return False

            # check TableEquation and TableMatrixEquation
            elif isinstance(value, self.allowed_types_equations):
                if name in self.__functions:
                    self.__functions[name] = value
                    return True
                else:
                    logger.warning(f"{name} not found!")
                    return False

            else:
                logger.error("Value must be TableData or TableEquation")
                return False

        except Exception as e:
            logger.error(f"Updating a property failed!, {e}")
            return False

    def _rename(
            self,
            name: str,
            new_name: str
    ) -> bool:
        '''
        Rename a property/functions

        Parameters
        ----------
        name : str
            name of the property/function
        new_name : str
            new name of the property/function

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # check
            if name in self.__properties:
                self.__properties[new_name] = self.__properties.pop(name)
                return True
            elif name in self.__functions:
                self.__functions[new_name] = self.__functions.pop(name)
                return True
            else:
                logger.warning(f"{name} not found!")
                return False
        except Exception as e:
            raise Exception("Renaming a property failed!, ", e)

    def _clean(self):
        '''
        Clean properties/functions (dictionaries)

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            self.__properties = {}
            self.__functions = {}
            return True
        except Exception as e:
            logger.error(f"Cleaning properties/functions failed!, {e}")
            return False

compbuilder

CompBuilder

Bases: CompExporter

Used to build thermodb library

Source code in pyThermoDB/builder/compbuilder.py

class CompBuilder(CompExporter):
    """Used to build thermodb library"""

    # vars
    __data = {}
    # thermodb name (optional)
    __thermodb_name: str | None = None
    # message
    __message: str | None = None
    # thermodb version
    build_version = __version__

    def __init__(
        self,
        thermodb_name: Optional[str] = None,
        message: Optional[str] = None
    ):
        '''
        Initialize CompBuilder object

        Parameters
        ----------
        thermodb_name : str
            name of the thermodb (default is None)
        '''
        # init class
        super().__init__()
        # set name
        self.__thermodb_name = thermodb_name
        # set message
        self.__message = message if message is not None else 'CompBuilder instance created!'

        # ! reset data
        self.__data = {}

    @property
    def thermodb_name(self) -> str | None:
        '''
        Get thermodb name

        Returns
        -------
        str
            thermodb name
        '''
        # check name
        if self.__thermodb_name is None:
            # return default name
            return 'thermodb'
        return self.__thermodb_name

    @property
    def message(self) -> str:
        '''
        Get message

        Returns
        -------
        str
            message
        '''
        # check message
        if self.__message is None:
            # return default message
            return 'CompBuilder instance created!'
        return self.__message

    def add_data(
        self,
        name: str,
        value: Union[
            TableData, TableEquation, dict, TableMatrixData, TableMatrixEquation
        ]
    ):
        '''
        Add TableData/TableEquation

        Parameters
        ----------
        name : str
            data name
        value : TableData | TableEquation | dict
            value of the property/function

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # check
            if value is None:
                raise Exception('Value is required')

            # check
            if name is None:
                raise Exception('Name is required')

            # check TableData | TableEquation | dict | TableMatrixData | TableMatrixEquation
            allowed_types = (
                TableData,
                TableEquation,
                dict,
                TableMatrixData,
                TableMatrixEquation
            )

            # check allowed types
            if isinstance(value, allowed_types):
                self.__data[name] = value
                return True
            else:
                logger.error(f'Invalid type: {type(value)}')
                return False
        except Exception as e:
            logger.error(f'Adding data failed!, {e}')
            return False

    def delete_data(self, name: str) -> bool:
        '''
        Delete data by name

        Parameters
        ----------
        name : str
            data name

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            if name in self.__data:
                del self.__data[name]
                #
                return True
            else:
                logger.error('Data not found')
                return False
        except Exception as e:
            logger.error(f'Deleting data failed!, {e}')
            return False

    def rename_data(
            self,
            name: str,
            new_name: str
    ):
        '''
        Rename data

        Parameters
        ----------
        name : str
            data name
        new_name : str
            new data name

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            if name in self.__data:
                self.__data[new_name] = self.__data.pop(name)
                return True
            else:
                logger.error('Data not found')
                return False
        except Exception as e:
            logger.error(f'Renaming data failed!, {e}')
            return False

    def list_data(self):
        '''
        List the thermo data added `before saving`

        Parameters
        ----------
        None

        Returns
        -------
        data : dict
            data dictionary

        Notes
        -----
        The thermo objects are created by

        1. thermo_db.build_data()
        2. thermo_db.build_equations()
        '''
        try:
            return self.__data
        except Exception as e:
            logger.error(f'Listing data failed!, {e}')
            return {}

    def build(self):
        '''
        Build thermodb

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # build library
            for name, value in self.__data.items():
                self._add(name, value)

            return True
        except Exception as e:
            logger.error(f'Building library failed!, {e}')
            return False

    def export_yml(self, component_name: str):
        '''
        Export thermodb

        Parameters
        ----------
        component_name : str
            component name

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # data
            _to_comp = {}

            _data_yml = {
                'DATA': {},
                'EQUATIONS': {},
                'MATRIX-DATA': {},
                'MATRIX-EQUATIONS': {}
            }
            # get TableData
            for i, (name, value) in enumerate(self.properties.items()):
                if isinstance(value, TableData):
                    _yml = value.to_dict()
                    # add chunk
                    _data_yml['DATA'][str(name)] = _yml

            # get TableMatrixData
            for i, (name, value) in enumerate(self.properties.items()):
                if isinstance(value, TableMatrixData):
                    _yml = value.to_dict()
                    # add chunk
                    _data_yml['MATRIX-DATA'][str(name)] = _yml

            # get TableEquation
            for i, (name, value) in enumerate(self.functions.items()):
                if isinstance(value, TableEquation):
                    _yml = value.to_dict()
                    # add chunk
                    _data_yml['EQUATIONS'][str(name)] = _yml

            # get TableMatrixEquation
            for i, (name, value) in enumerate(self.functions.items()):
                if isinstance(value, TableMatrixEquation):
                    _yml = value.to_dict()
                    # add chunk
                    _data_yml['MATRIX-EQUATIONS'][str(name)] = _yml

            # for component
            _to_comp[component_name] = _data_yml

            # convert to yml
            res = yaml.dump(_to_comp)

            # save
            with open(f"{component_name}.yml", "w") as f:
                f.write(res)

            # return
            return True

        except Exception as e:
            logger.error(f'Exporting yml failed!, {e}')
            return False

    def export_data_structure(
            self,
            component_name: str
    ) -> bool:
        '''
        Export yml of thermodb containing TableData and TableEquation objects

        Parameters
        ----------
        component_name : str
            component name

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # build
            self.build()

            # yml
            return self.export_yml(component_name)
        except Exception as e:
            logger.error(f'Exporting data structure failed!, {e}')
            return False

    def check(self) -> dict:
        '''
        Check library

        Returns
        -------
        res : dict
            list of all properties and functions registered
        '''
        try:
            # res
            res = {}
            # check properties
            res = {**self.check_properties(), **self.check_functions()}
            return res
        except Exception as e:
            logger.error(f'Checking library failed!, {e}')
            return {}

    def check_properties(self) -> dict[str, TableData | TableMatrixData]:
        '''
        Check properties

        Returns
        -------
        dict
            all properties registered
        '''
        try:
            # check library
            return self.properties
        except Exception as e:
            raise Exception('Checking properties failed!, ', e)

    def check_property(
        self,
        thermo_name: str
    ) -> TableData | TableMatrixData:
        '''
        Check properties

        Parameters
        ----------
        thermo_name : str
            name of the thermodynamic property

        Returns
        -------
        TableMatrixData | TableData
            property registered
        '''
        try:
            # check library
            return self.properties[thermo_name]
        except Exception as e:
            raise Exception('Checking properties failed!, ', e)

    def select_property(
        self,
            thermo_name: str
    ) -> TableData | TableMatrixData:
        '''
        Select a thermodynamic property

        Parameters
        ----------
        thermo_name : str
            name of the thermodynamic property

        Returns
        -------
        TableMatrixData | TableData
            property registered in the thermodb
        '''
        try:
            # check library
            return self.properties[thermo_name]
        except Exception as e:
            raise Exception('Selecting a property failed!, ', e)

    def check_functions(self) -> dict[str, TableEquation | TableMatrixEquation]:
        '''
        Check all functions

        Returns
        -------
        dict
            all functions registered
        '''
        try:
            # check library
            return self.functions
        except Exception as e:
            raise Exception('Checking functions failed!, ', e)

    def check_function(
        self,
        name: str
    ) -> TableEquation | TableMatrixEquation:
        '''
        Check functions by name

        Parameters
        ----------
        name : str
            function name

        Returns
        -------
        TableEquation | TableMatrixEquation
            function registered in the thermodb
        '''
        try:
            # check library
            return self.functions[name]
        except Exception as e:
            raise Exception('Checking functions failed!, ', e)

    def select_function(
        self,
        function_name: str
    ) -> TableEquation | TableMatrixEquation:
        '''
        Select a function registered in the thermodb

        Parameters
        ----------
        function_name : str
            name of the thermodynamic function

        Returns
        -------
        TableMatrixEquation | TableEquation
            function registered in the thermodb
        '''
        try:
            # check library
            return self.functions[function_name]
        except Exception as e:
            raise Exception('Selecting a function failed!, ', e)

    def select(
        self,
        thermo_name: str
    ) -> Union[
        TableData,
        TableMatrixData,
        TableEquation,
        TableMatrixEquation
    ]:
        '''
        Select a thermodynamic property or function registered in the thermodb

        Parameters
        ----------
        thermo_name : str
            name of the thermodynamic property

        Returns
        -------
        TableMatrixData | TableData | TableEquation | TableMatrixEquation
            property defined in the thermodb
        '''
        try:
            # SECTION 1: check if the property exists in both functions and properties
            check_list = list(self.functions.keys()) + \
                list(self.properties.keys())
            # check if the property exists in both functions and properties
            if (thermo_name not in check_list):
                # raise
                raise Exception(
                    'Property exists in both functions and properties!')

            # SECTION 2: check if the property is a function or a property
            if thermo_name in self.functions:
                # check if the property is a function
                return self.functions[thermo_name]
            elif thermo_name in self.properties:
                # check if the property is a property
                return self.properties[thermo_name]
            else:
                # check if the property is a property in the thermodb
                raise Exception('Property not found in the thermodb!')
        except Exception as e:
            raise Exception('Selecting a thermodynamic property failed!, ', e)

    def retrieve(
        self,
        property_source: str,
        message: Optional[str] = None,
        symbol_format: Literal[
            'alphabetic', 'numeric'
        ] = 'alphabetic'
    ):
        '''
        Retrieve a thermodynamic property from the thermodb for only TableData and TableMatrixData

        Parameters
        ----------
        property_source : str
            source of the property to retrieve such as 'general-data | dH_IG'
        message : str
            message to display (default is None)
        symbol_format : str
            symbol format to use (default is 'alphabetic'), needed for `TableMatrixData`

        Returns
        -------
        prop: DataResult
            property object

        Notes
        -----
        The property source is a string containing the name of the property source and the name of the property separated by a pipe (|) character.
        For example,

        1- 'general-data | dH_IG' means that the property is in the general-data source and the name of the property is dH_IG.
        2- 'nrtl-data | alpha_ij | methanol | ethanol' means that the property is in the nrtl-data source and the name of the property is alpha_ij and the components are methanol and ethanol.
        '''
        try:
            # split source
            source = property_source.split('|')
            # num
            source_num = len(source)

            # SECTION: check message
            message = message if message is not None else f'Retrieving used for {property_source}!'

            # SECTION: property source
            prop_src = self.select(source[0].strip())

            # SECTION: property name
            # check
            if isinstance(prop_src, TableData):
                # check length
                if source_num != 2:
                    raise ValueError(
                        f"Invalid source format! {property_source}")
                # get property
                prop = prop_src.get_property(
                    source[1].strip(), message=message)
                # return
                return prop
            elif isinstance(prop_src, TableMatrixData):
                # NOTE: check strring format
                if source_num == 2:
                    # property name full format
                    prop_name = source[1].strip()

                    # check if the property name is in the format of 'Alpha_i_j'
                    extracted = prop_name.split('_')
                    # count
                    if len(extracted) != 3:
                        raise ValueError(
                            f"Invalid source format! {property_source}, property name is required!")

                    # NOTE: get property (ij method)
                    prop = prop_src.ij(
                        prop_name, symbol_format=symbol_format, message=message)
                    # return
                    return prop
                elif source_num == 4:
                    # get components
                    component_names = source[2:]
                    # trim
                    component_names = [name.strip()
                                       for name in component_names]
                    # check length
                    if len(component_names) != 2:
                        raise ValueError(
                            f"Invalid source format! {property_source}, components are required!")

                    # NOTE: get property (get_matrix_property method)
                    prop = prop_src.get_matrix_property(source[1].strip(), component_names=component_names,
                                                        symbol_format=symbol_format, message=message)
                    # return
                    return prop
            else:
                raise Exception(
                    f"Property source is not a TableData object! {prop_src}")

        except Exception as e:
            raise Exception("Retrieving failed!, ", e)

    def save(
        self,
        filename: str,
        file_path: Optional[str] = None
    ) -> bool:
        """
        Saves the instance to a file using pickle

        Parameters
        ----------
        filename : str
            filename
        file_path : str
            file path (default is None)

        Returns
        -------
        res : bool
            True if success
        """
        try:
            # check filename
            if filename is None:
                raise Exception("Filename is required!")

            # build
            self.build()

            # file path setting
            if file_path is None:
                file_path = os.getcwd()

            # file full name
            filename = os.path.join(file_path, filename)

            # file name path
            if not filename.endswith('.pkl'):
                filename += '.pkl'

            # save
            with open(f'{filename}', 'wb') as f:
                pickle.dump(self, f)
            # res
            return True
        except Exception as e:
            logger.error(f'Saving CompBuilder instance failed!, {e}')
            return False

    @classmethod
    def load(cls, filename: str):
        """
        Loads a saved instance from a file using pickle

        Parameters
        ----------
        filename : str
            filename path

        Returns
        -------
        thermodb : object
            thermodb instance
        """
        try:
            with open(filename, 'rb') as f:
                return pickle.load(f)
        except Exception as e:
            raise Exception("Loading CompBuilder instance failed!", e)

    def clean(self) -> bool:
        '''
        Clean all data including properties/functions

        Returns
        -------
        res : bool
            True if success
        '''
        try:
            # clean
            # data
            self.__data = {}
            # properties/functions
            self._clean()

            # res
            return True
        except Exception as e:
            logger.error(f'Cleaning properties/functions failed!, {e}')
            return False

message: str property

Get message

Returns

str message

thermodb_name: str | None property

Get thermodb name

Returns

str thermodb name

__init__(thermodb_name=None, message=None)

Initialize CompBuilder object

Parameters

thermodb_name : str name of the thermodb (default is None)

Source code in pyThermoDB/builder/compbuilder.py

def __init__(
    self,
    thermodb_name: Optional[str] = None,
    message: Optional[str] = None
):
    '''
    Initialize CompBuilder object

    Parameters
    ----------
    thermodb_name : str
        name of the thermodb (default is None)
    '''
    # init class
    super().__init__()
    # set name
    self.__thermodb_name = thermodb_name
    # set message
    self.__message = message if message is not None else 'CompBuilder instance created!'

    # ! reset data
    self.__data = {}

add_data(name, value)

Add TableData/TableEquation

Parameters

name : str data name value : TableData | TableEquation | dict value of the property/function

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def add_data(
    self,
    name: str,
    value: Union[
        TableData, TableEquation, dict, TableMatrixData, TableMatrixEquation
    ]
):
    '''
    Add TableData/TableEquation

    Parameters
    ----------
    name : str
        data name
    value : TableData | TableEquation | dict
        value of the property/function

    Returns
    -------
    res : bool
        True if success
    '''
    try:
        # check
        if value is None:
            raise Exception('Value is required')

        # check
        if name is None:
            raise Exception('Name is required')

        # check TableData | TableEquation | dict | TableMatrixData | TableMatrixEquation
        allowed_types = (
            TableData,
            TableEquation,
            dict,
            TableMatrixData,
            TableMatrixEquation
        )

        # check allowed types
        if isinstance(value, allowed_types):
            self.__data[name] = value
            return True
        else:
            logger.error(f'Invalid type: {type(value)}')
            return False
    except Exception as e:
        logger.error(f'Adding data failed!, {e}')
        return False

build()

Build thermodb

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def build(self):
    '''
    Build thermodb

    Returns
    -------
    res : bool
        True if success
    '''
    try:
        # build library
        for name, value in self.__data.items():
            self._add(name, value)

        return True
    except Exception as e:
        logger.error(f'Building library failed!, {e}')
        return False

check()

Check library

Returns

res : dict list of all properties and functions registered

Source code in pyThermoDB/builder/compbuilder.py

def check(self) -> dict:
    '''
    Check library

    Returns
    -------
    res : dict
        list of all properties and functions registered
    '''
    try:
        # res
        res = {}
        # check properties
        res = {**self.check_properties(), **self.check_functions()}
        return res
    except Exception as e:
        logger.error(f'Checking library failed!, {e}')
        return {}

check_function(name)

Check functions by name

Parameters

name : str function name

Returns

TableEquation | TableMatrixEquation function registered in the thermodb

Source code in pyThermoDB/builder/compbuilder.py

def check_function(
    self,
    name: str
) -> TableEquation | TableMatrixEquation:
    '''
    Check functions by name

    Parameters
    ----------
    name : str
        function name

    Returns
    -------
    TableEquation | TableMatrixEquation
        function registered in the thermodb
    '''
    try:
        # check library
        return self.functions[name]
    except Exception as e:
        raise Exception('Checking functions failed!, ', e)

check_functions()

Check all functions

Returns

dict all functions registered

Source code in pyThermoDB/builder/compbuilder.py

def check_functions(self) -> dict[str, TableEquation | TableMatrixEquation]:
    '''
    Check all functions

    Returns
    -------
    dict
        all functions registered
    '''
    try:
        # check library
        return self.functions
    except Exception as e:
        raise Exception('Checking functions failed!, ', e)

check_properties()

Check properties

Returns

dict all properties registered

Source code in pyThermoDB/builder/compbuilder.py

def check_properties(self) -> dict[str, TableData | TableMatrixData]:
    '''
    Check properties

    Returns
    -------
    dict
        all properties registered
    '''
    try:
        # check library
        return self.properties
    except Exception as e:
        raise Exception('Checking properties failed!, ', e)

check_property(thermo_name)

Check properties

Parameters

thermo_name : str name of the thermodynamic property

Returns

TableMatrixData | TableData property registered

Source code in pyThermoDB/builder/compbuilder.py

def check_property(
    self,
    thermo_name: str
) -> TableData | TableMatrixData:
    '''
    Check properties

    Parameters
    ----------
    thermo_name : str
        name of the thermodynamic property

    Returns
    -------
    TableMatrixData | TableData
        property registered
    '''
    try:
        # check library
        return self.properties[thermo_name]
    except Exception as e:
        raise Exception('Checking properties failed!, ', e)

clean()

Clean all data including properties/functions

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def clean(self) -> bool:
    '''
    Clean all data including properties/functions

    Returns
    -------
    res : bool
        True if success
    '''
    try:
        # clean
        # data
        self.__data = {}
        # properties/functions
        self._clean()

        # res
        return True
    except Exception as e:
        logger.error(f'Cleaning properties/functions failed!, {e}')
        return False

delete_data(name)

Delete data by name

Parameters

name : str data name

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def delete_data(self, name: str) -> bool:
    '''
    Delete data by name

    Parameters
    ----------
    name : str
        data name

    Returns
    -------
    res : bool
        True if success
    '''
    try:
        if name in self.__data:
            del self.__data[name]
            #
            return True
        else:
            logger.error('Data not found')
            return False
    except Exception as e:
        logger.error(f'Deleting data failed!, {e}')
        return False

export_data_structure(component_name)

Export yml of thermodb containing TableData and TableEquation objects

Parameters

component_name : str component name

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def export_data_structure(
        self,
        component_name: str
) -> bool:
    '''
    Export yml of thermodb containing TableData and TableEquation objects

    Parameters
    ----------
    component_name : str
        component name

    Returns
    -------
    res : bool
        True if success
    '''
    try:
        # build
        self.build()

        # yml
        return self.export_yml(component_name)
    except Exception as e:
        logger.error(f'Exporting data structure failed!, {e}')
        return False

export_yml(component_name)

Export thermodb

Parameters

component_name : str component name

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def export_yml(self, component_name: str):
    '''
    Export thermodb

    Parameters
    ----------
    component_name : str
        component name

    Returns
    -------
    res : bool
        True if success
    '''
    try:
        # data
        _to_comp = {}

        _data_yml = {
            'DATA': {},
            'EQUATIONS': {},
            'MATRIX-DATA': {},
            'MATRIX-EQUATIONS': {}
        }
        # get TableData
        for i, (name, value) in enumerate(self.properties.items()):
            if isinstance(value, TableData):
                _yml = value.to_dict()
                # add chunk
                _data_yml['DATA'][str(name)] = _yml

        # get TableMatrixData
        for i, (name, value) in enumerate(self.properties.items()):
            if isinstance(value, TableMatrixData):
                _yml = value.to_dict()
                # add chunk
                _data_yml['MATRIX-DATA'][str(name)] = _yml

        # get TableEquation
        for i, (name, value) in enumerate(self.functions.items()):
            if isinstance(value, TableEquation):
                _yml = value.to_dict()
                # add chunk
                _data_yml['EQUATIONS'][str(name)] = _yml

        # get TableMatrixEquation
        for i, (name, value) in enumerate(self.functions.items()):
            if isinstance(value, TableMatrixEquation):
                _yml = value.to_dict()
                # add chunk
                _data_yml['MATRIX-EQUATIONS'][str(name)] = _yml

        # for component
        _to_comp[component_name] = _data_yml

        # convert to yml
        res = yaml.dump(_to_comp)

        # save
        with open(f"{component_name}.yml", "w") as f:
            f.write(res)

        # return
        return True

    except Exception as e:
        logger.error(f'Exporting yml failed!, {e}')
        return False

list_data()

List the thermo data added before saving

Parameters

None

Returns

data : dict data dictionary

Notes

The thermo objects are created by

1. thermo_db.build_data()
2. thermo_db.build_equations()

Source code in pyThermoDB/builder/compbuilder.py

def list_data(self):
    '''
    List the thermo data added `before saving`

    Parameters
    ----------
    None

    Returns
    -------
    data : dict
        data dictionary

    Notes
    -----
    The thermo objects are created by

    1. thermo_db.build_data()
    2. thermo_db.build_equations()
    '''
    try:
        return self.__data
    except Exception as e:
        logger.error(f'Listing data failed!, {e}')
        return {}

load(filename) classmethod

Loads a saved instance from a file using pickle

Parameters

filename : str filename path

Returns

thermodb : object thermodb instance

Source code in pyThermoDB/builder/compbuilder.py

@classmethod
def load(cls, filename: str):
    """
    Loads a saved instance from a file using pickle

    Parameters
    ----------
    filename : str
        filename path

    Returns
    -------
    thermodb : object
        thermodb instance
    """
    try:
        with open(filename, 'rb') as f:
            return pickle.load(f)
    except Exception as e:
        raise Exception("Loading CompBuilder instance failed!", e)

rename_data(name, new_name)

Rename data

Parameters

name : str data name new_name : str new data name

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def rename_data(
        self,
        name: str,
        new_name: str
):
    '''
    Rename data

    Parameters
    ----------
    name : str
        data name
    new_name : str
        new data name

    Returns
    -------
    res : bool
        True if success
    '''
    try:
        if name in self.__data:
            self.__data[new_name] = self.__data.pop(name)
            return True
        else:
            logger.error('Data not found')
            return False
    except Exception as e:
        logger.error(f'Renaming data failed!, {e}')
        return False

retrieve(property_source, message=None, symbol_format='alphabetic')

Retrieve a thermodynamic property from the thermodb for only TableData and TableMatrixData

Parameters

property_source : str source of the property to retrieve such as 'general-data | dH_IG' message : str message to display (default is None) symbol_format : str symbol format to use (default is 'alphabetic'), needed for TableMatrixData

Returns

prop: DataResult property object

Notes

The property source is a string containing the name of the property source and the name of the property separated by a pipe (|) character. For example,

1- 'general-data | dH_IG' means that the property is in the general-data source and the name of the property is dH_IG. 2- 'nrtl-data | alpha_ij | methanol | ethanol' means that the property is in the nrtl-data source and the name of the property is alpha_ij and the components are methanol and ethanol.

Source code in pyThermoDB/builder/compbuilder.py

def retrieve(
    self,
    property_source: str,
    message: Optional[str] = None,
    symbol_format: Literal[
        'alphabetic', 'numeric'
    ] = 'alphabetic'
):
    '''
    Retrieve a thermodynamic property from the thermodb for only TableData and TableMatrixData

    Parameters
    ----------
    property_source : str
        source of the property to retrieve such as 'general-data | dH_IG'
    message : str
        message to display (default is None)
    symbol_format : str
        symbol format to use (default is 'alphabetic'), needed for `TableMatrixData`

    Returns
    -------
    prop: DataResult
        property object

    Notes
    -----
    The property source is a string containing the name of the property source and the name of the property separated by a pipe (|) character.
    For example,

    1- 'general-data | dH_IG' means that the property is in the general-data source and the name of the property is dH_IG.
    2- 'nrtl-data | alpha_ij | methanol | ethanol' means that the property is in the nrtl-data source and the name of the property is alpha_ij and the components are methanol and ethanol.
    '''
    try:
        # split source
        source = property_source.split('|')
        # num
        source_num = len(source)

        # SECTION: check message
        message = message if message is not None else f'Retrieving used for {property_source}!'

        # SECTION: property source
        prop_src = self.select(source[0].strip())

        # SECTION: property name
        # check
        if isinstance(prop_src, TableData):
            # check length
            if source_num != 2:
                raise ValueError(
                    f"Invalid source format! {property_source}")
            # get property
            prop = prop_src.get_property(
                source[1].strip(), message=message)
            # return
            return prop
        elif isinstance(prop_src, TableMatrixData):
            # NOTE: check strring format
            if source_num == 2:
                # property name full format
                prop_name = source[1].strip()

                # check if the property name is in the format of 'Alpha_i_j'
                extracted = prop_name.split('_')
                # count
                if len(extracted) != 3:
                    raise ValueError(
                        f"Invalid source format! {property_source}, property name is required!")

                # NOTE: get property (ij method)
                prop = prop_src.ij(
                    prop_name, symbol_format=symbol_format, message=message)
                # return
                return prop
            elif source_num == 4:
                # get components
                component_names = source[2:]
                # trim
                component_names = [name.strip()
                                   for name in component_names]
                # check length
                if len(component_names) != 2:
                    raise ValueError(
                        f"Invalid source format! {property_source}, components are required!")

                # NOTE: get property (get_matrix_property method)
                prop = prop_src.get_matrix_property(source[1].strip(), component_names=component_names,
                                                    symbol_format=symbol_format, message=message)
                # return
                return prop
        else:
            raise Exception(
                f"Property source is not a TableData object! {prop_src}")

    except Exception as e:
        raise Exception("Retrieving failed!, ", e)

save(filename, file_path=None)

Saves the instance to a file using pickle

Parameters

filename : str filename file_path : str file path (default is None)

Returns

res : bool True if success

Source code in pyThermoDB/builder/compbuilder.py

def save(
    self,
    filename: str,
    file_path: Optional[str] = None
) -> bool:
    """
    Saves the instance to a file using pickle

    Parameters
    ----------
    filename : str
        filename
    file_path : str
        file path (default is None)

    Returns
    -------
    res : bool
        True if success
    """
    try:
        # check filename
        if filename is None:
            raise Exception("Filename is required!")

        # build
        self.build()

        # file path setting
        if file_path is None:
            file_path = os.getcwd()

        # file full name
        filename = os.path.join(file_path, filename)

        # file name path
        if not filename.endswith('.pkl'):
            filename += '.pkl'

        # save
        with open(f'{filename}', 'wb') as f:
            pickle.dump(self, f)
        # res
        return True
    except Exception as e:
        logger.error(f'Saving CompBuilder instance failed!, {e}')
        return False

select(thermo_name)

Select a thermodynamic property or function registered in the thermodb

Parameters

thermo_name : str name of the thermodynamic property

Returns

TableMatrixData | TableData | TableEquation | TableMatrixEquation property defined in the thermodb

Source code in pyThermoDB/builder/compbuilder.py

def select(
    self,
    thermo_name: str
) -> Union[
    TableData,
    TableMatrixData,
    TableEquation,
    TableMatrixEquation
]:
    '''
    Select a thermodynamic property or function registered in the thermodb

    Parameters
    ----------
    thermo_name : str
        name of the thermodynamic property

    Returns
    -------
    TableMatrixData | TableData | TableEquation | TableMatrixEquation
        property defined in the thermodb
    '''
    try:
        # SECTION 1: check if the property exists in both functions and properties
        check_list = list(self.functions.keys()) + \
            list(self.properties.keys())
        # check if the property exists in both functions and properties
        if (thermo_name not in check_list):
            # raise
            raise Exception(
                'Property exists in both functions and properties!')

        # SECTION 2: check if the property is a function or a property
        if thermo_name in self.functions:
            # check if the property is a function
            return self.functions[thermo_name]
        elif thermo_name in self.properties:
            # check if the property is a property
            return self.properties[thermo_name]
        else:
            # check if the property is a property in the thermodb
            raise Exception('Property not found in the thermodb!')
    except Exception as e:
        raise Exception('Selecting a thermodynamic property failed!, ', e)

select_function(function_name)

Select a function registered in the thermodb

Parameters

function_name : str name of the thermodynamic function

Returns

TableMatrixEquation | TableEquation function registered in the thermodb

Source code in pyThermoDB/builder/compbuilder.py

def select_function(
    self,
    function_name: str
) -> TableEquation | TableMatrixEquation:
    '''
    Select a function registered in the thermodb

    Parameters
    ----------
    function_name : str
        name of the thermodynamic function

    Returns
    -------
    TableMatrixEquation | TableEquation
        function registered in the thermodb
    '''
    try:
        # check library
        return self.functions[function_name]
    except Exception as e:
        raise Exception('Selecting a function failed!, ', e)

select_property(thermo_name)

Select a thermodynamic property

Parameters

thermo_name : str name of the thermodynamic property

Returns

TableMatrixData | TableData property registered in the thermodb

Source code in pyThermoDB/builder/compbuilder.py

def select_property(
    self,
        thermo_name: str
) -> TableData | TableMatrixData:
    '''
    Select a thermodynamic property

    Parameters
    ----------
    thermo_name : str
        name of the thermodynamic property

    Returns
    -------
    TableMatrixData | TableData
        property registered in the thermodb
    '''
    try:
        # check library
        return self.properties[thermo_name]
    except Exception as e:
        raise Exception('Selecting a property failed!, ', e)