PyThermoDB

https://pythermodb.readthedocs.io/en/stable/
Admin
PyThermoDB is a Python library that inspects databooks and tables, builds thermodynamic property...
Tokens:718,416
Snippets:3,009
Trust Score:9.6
Update:8 hours ago
Show doc for...
Tokens:
Raw
### Install PyThermoDB with pip

Source: https://pythermodb.readthedocs.io/en/stable/

Install the PyThermoDB package using pip.

```bash
pip install pyThermoDB
```

--------------------------------

### Import and print version

Source: https://pythermodb.readthedocs.io/en/stable/

Import PyThermoDB and print its version to verify installation.

```python
import pyThermoDB as ptdb
print(ptdb.__version__)
```

--------------------------------

### Generate property mapping example

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Shows how to use DataChecker.generate_property_mapping to get a dictionary mapping property names to symbols for a databook. The output lists properties like 'ideal-gas-heat-capacity' mapped to 'Cp_IG'.

```python
>>> checker = DataChecker('path/to/databooks')
>>> property_mapping = checker.generate_property_mapping('ExampleDatabook')
>>> print(property_mapping)
{
    'ideal-gas-heat-capacity': 'Cp_IG',
    'Molecular-Weight': 'MW',
    'Critical-Temperature': 'Tc',
    'Critical-Pressure': 'Pc',
    'Critical-Molar-Volume': 'Vc',
    'Critical-Compressibility-Factor': 'Zc',
    'Acentric-Factor': 'AcFa',
    'Enthalpy-of-Formation': 'EnFo',
    'Gibbs-Energy-of-Formation': 'GiEnFo',
    'vapor-pressure': 'VaPr',
    'a constant parameter': 'a',
    'b': 'b',
    'c': 'c',
    'alpha': 'alpha'
}
```

--------------------------------

### Initialize pyThermoDB, build data and equation, save and load ThermoDB

Source: https://pythermodb.readthedocs.io/en/stable/quickstart/

This snippet shows the complete quickstart workflow: initialize references with ptdb.init(), build a TableData and TableEquation for 'carbon dioxide', save them to a ThermoDB file, and load it back. It prints the molecular weight and a calculated value, then checks the loaded database and retrieves a property.

```python
import os
import pyThermoDB as ptdb

# 1) initialize references
tdb = ptdb.init()

# 2) build thermo properties
component = "carbon dioxide"
data_obj = tdb.build_data(component, 1, 2)
eq_obj = tdb.build_equation(component, 1, 3)

print(data_obj.get_property("MW"))
print(eq_obj.cal(T=298.15))

# 3) create and save thermodb
db = ptdb.build_thermodb(thermodb_name="co2-demo")
db.add_data("general", data_obj)
db.add_data("vapor-pressure", eq_obj)
db.save("co2-demo.pkl", file_path=os.getcwd())

# 4) load and use
loaded = ptdb.load_thermodb(os.path.join(os.getcwd(), "co2-demo.pkl"))
print(loaded.check())
print(loaded.retrieve("general | MW", message="molecular weight"))
```

--------------------------------

### __init__(custom_ref=None, data_source='local')

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Creates a database facade from bundled or custom reference data.

```APIDOC
## __init__(custom_ref=None, data_source='local')

### Description
Creates a database facade from bundled or custom reference data.

### Method
__init__

### Parameters
- **custom_ref** (dict | str) - Optional - Custom reference definition or reference path passed to ManageData.
- **data_source** (str) - Optional, default='local' - Label describing the source used by the caller.

### Returns
- None

### Notes
Custom-reference parsing and validation are delegated to ManageData.
```

--------------------------------

### __init__ method implementation

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Initializes CompBuilder with optional thermodb_name and message. Reads configuration, initializes CompExporter, ensures a shared CompTools_ instance, and sets internal attributes.

```python
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)
    message : str
        message (default is None)
    '''
    # SECTION: get config
    config = get_config()
    # ! set build type
    self._build_type = config.build_type
    # ! set component identifiers
    self._component_name = config.component_name
    self._component_formula = config.component_formula
    self._component_state = config.component_state

    # SECTION: super init
    CompExporter.__init__(self)

    # NOTE: ensure a shared CompTools_ exists and attach to the instance
    if CompBuilder.CompTools_ is None:
        try:
            CompBuilder.CompTools_ = CompTools()
        except Exception:
            CompBuilder.CompTools_ = None

    # SECTION: set attributes
    # 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 = {}
```

--------------------------------

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

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Gets component data from the database via API. It consists of two steps: step1 gets thermo data for a component, step2 gets the equation for the data (parameters).

```APIDOC
## get_component_data_api(component_name, databook_id, table_id, dataframe=False)

### Description
Gets component data from the database via API. It consists of two steps: step1 gets thermo data for a component, step2 gets the equation for the data (parameters).

### Method
Function call

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

### Returns
- **component_data** (object | pandas dataframe) - component data

### Example
```python
component_data = thermo.get_component_data_api(
    component_name='Carbon dioxide',
    databook_id=1,
    table_id=2,
    dataframe=True
)
```
```

--------------------------------

### __init__(custom_ref=None, data_source='local')

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Create a database facade from bundled or custom reference data. Custom-reference parsing and validation are delegated to ManageData.

```APIDOC
## __init__(custom_ref=None, data_source='local')

### Description
Create a database facade from bundled or custom reference data. Custom-reference parsing and validation are delegated to `ManageData`.

### Parameters
- **custom_ref** (dict | str, optional) - Custom reference definition or reference path passed to `ManageData`.
- **data_source** (str, default='local') - Label describing the source used by the caller.

### Returns
None

### Notes
Custom-reference parsing and validation are delegated to `ManageData`.

### Source Code
```python
def __init__(
    self,
    custom_ref=None,
    data_source='local'
):
    """Create a database facade from bundled or custom reference data.

    Parameters
    ----------
    custom_ref : dict | str, optional
        Custom reference definition or reference path passed to ``ManageData``.
    data_source : str, default='local'
        Label describing the source used by the caller.

    Returns
    -------
    None

    Notes
    -----
    Custom-reference parsing and validation are delegated to ``ManageData``.
    """
    # NOTE: set
    self.data_source = data_source
    self.custom_ref = custom_ref

    # LINK: ManageData init
    ManageData.__init__(self, custom_ref=custom_ref)
```
```

--------------------------------

### Reference Rule Structure Example

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Example of the reference rule structure generated by generate_reference_rules, containing DATA and EQUATIONS sections mapping properties to symbols.

```python
{ 'DATA': { 'Property1': 'Symbol1', 'Property2': 'Symbol2', ... }, 'EQUATIONS': { 'Property3': 'Symbol3', ... } }
```

--------------------------------

### ManageData: Get tables

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Method to get a table list of a selected databook. Accepts databook as a string or integer. Returns a list of tables with type and ID, and raises an error if the databook is not found.

```python
try:
    # list tables
    if isinstance(databook, str):
        # ! case insensitive
        databook_ = [
            db for db in self.databook if db.lower() == databook.lower().strip()
        ]
        # check
        if len(databook_) == 0:
            raise ValueError(f"Databook {databook} not found!")

        # set name
        databook = databook_[0]

        # get databook
        _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}]"
                ]
            )
        # ! interaction-data
        elif tb.get('interaction_data') is not None:
            tables.append(
                [tb['table'], "interaction-data", f"[{i+1}]"])

        # ! dataset
        elif tb.get('dataset') is not None:
            tables.append([tb['table'], "dataset", f"[{i+1}]"])
```

--------------------------------

### ThermoDatabook.__init__

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Initializes a new ThermoDatabook instance with a name and optional description.

```APIDOC
## ThermoDatabook.__init__

### Description
Initializes a new ThermoDatabook instance with a name and optional description.

### Method
Constructor

### Signature
`ThermoDatabook(databook_name: str, description: Optional[str] = None)`

### Parameters
- **databook_name** (str) - Required - The name of the databook.
- **description** (Optional[str]) - Optional - The description of the databook, by default None.

### Returns
None
```

--------------------------------

### cal_integral method with docstring example

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Calculates an integral using the loaded parameters and the body_integral equation. The docstring shows an example call: res = cal_integral(T1=120,T2=150) followed by print(res).

```python
    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
```

--------------------------------

### ThermoDatabook.__init__

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Initializes a new ThermoDatabook instance with a name and optional description.

```APIDOC
## ThermoDatabook.__init__

### Description
Initializes the ThermoDatabook instance.

### Method
Constructor

### Parameters
- **databook_name** (str) - Required - The name of the databook.
- **description** (Optional[str]) - Optional - The description of the databook, by default None.

### Request Example
```python
databook = ThermoDatabook(databook_name="my_databook", description="My databook")
```

### Response
No return value.
```

--------------------------------

### Building mixture thermodb with logging and reference thermodb

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Code snippet showing the process of building a mixture thermodb, including logging success/failure, creating a ReferenceThermoDB, initializing a MixtureThermoDB, and timing the operation. It raises an exception if building fails.

```python
# >> log
            if verbose:
                if build_res_:
                    logging.info(
                        f"Mixture thermodb '{thermodb_name}' built successfully."
                    )
                else:
                    logging.error(
                        f"Building mixture thermodb '{thermodb_name}' failed!"
                    )

        # SECTION: ComponentThermoDB settings
        # NOTE: reference thermodb
        # # REVIEW
        reference_thermodb = ReferenceThermoDB(
            reference=reference,
            contents=[reference_content],
            configs=mixture_reference_configs,
            rules=reference_rules,
            labels=labels,
            ignore_labels=ignore_labels,
            ignore_props=ignore_props
        )
        # NOTE: init ComponentThermoDB
        # init ComponentThermoDB
        component_thermodb = MixtureThermoDB(
            components=components,
            thermodb=thermodb_comp,
            reference_thermodb=reference_thermodb,
        )

        # LINK: end time
        if verbose:
            end_time = time.time()
            elapsed_time = end_time - start_time
            logging.info(
                f"Mixture thermodb check and build completed in {elapsed_time:.2f} seconds."
            )

        # return
        return component_thermodb
    except Exception as e:
        raise Exception(
            f"Building mixture:::{mixture_ids} thermodb failed! {e}")
```

--------------------------------

### get_property usage examples

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Example calls to get_property showing how to retrieve a property by name, by column index (1-based), and with optional mixture parameters. The first two calls return the same value for 'Alpha_i_1' of ethanol.

```python
get_property('Alpha_i_1', 'ethanol')
{'value': 0.3, 'unit': '', 'symbol': 'Alpha_i_1', 'description': 'Non-randomness parameter Alpha_i_1'}
get_property(4, 'ethanol')
{'value': 0.3, 'unit': '', 'symbol': 'Alpha_i_1', 'description': 'Non-randomness parameter Alpha_i_1'}
get_property('Alpha_i_1', 'ethanol', mixture_name='methanol | ethanol', component_key='Name-State', mixture_key='Name')
```

--------------------------------

### get_component_data_api method implementation

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Fetches component data from the API. The method signature includes component_name, databook_id, table_id, and dataframe parameters. The docstring describes a two-step process: get thermo data and get equation parameters.

```python
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
    '''
```

--------------------------------

### init_ref method implementation

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Validates configured reference sources and populates file paths. Returns True on success, False otherwise. Checks existence of YAML, YAML-compatible .yaml, Markdown, CSV, and symbol paths; errors are logged and converted to False.

```python
def init_ref(self):
    # ... (implementation not shown in source)
    pass
```

--------------------------------

### List Components with list_components and list_components_info

Source: https://pythermodb.readthedocs.io/en/stable/search/

Use tdb.list_components and tdb.list_components_info to list all components. Both return results in dict format.

```python
print(tdb.list_components(res_format="dict"))
print(tdb.list_components_info(res_format="dict"))
```

--------------------------------

### Example: using ref with custom reference

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Example usage of the ref function with a custom reference dictionary containing a reference YAML file and table CSV files. It initializes the app and calls ptdb.ref with the custom_reference argument.

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

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

--------------------------------

### cal_second_derivative method with docstring example

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Calculates the second derivative using the body_second_derivative equation. Prints a warning if the derivative is not defined. The docstring shows an example call: res = cal_second_derivative(T=120,P=1) followed by print(res).

```python
    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)
```

--------------------------------

### list_all_components method implementation

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Lists all components from all CSV files in the databook directory. For each file, it extracts the specified column (default 'Name'), builds component info with databook, database_id, table_name, table_id, and data_type. Raises an exception if the source is not found or on any error.

```python
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}')
```

--------------------------------

### cal_first_derivative method with docstring example

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Calculates the first derivative using the body_first_derivative equation. Prints a warning if the derivative is not defined. The docstring shows an example call: res = cal_first_derivative(T=120,P=1) followed by print(res).

```python
    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)
```

--------------------------------

### init(custom_reference=None, **kwargs)

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Initializes the ThermoDB app to check and build thermodynamic data and equations. Accepts an optional custom reference (dict or YAML file path) and additional keyword arguments for logging mode. Returns a ThermoDB object.

```APIDOC
## init(custom_reference=None, **kwargs)

### Description
Initializes the ThermoDB app to check and build thermodynamic data and equations. Accepts an optional custom reference (dict or YAML file path) and additional keyword arguments for logging mode. Returns a ThermoDB object.

### Method
Function call

### Endpoint
`ptdb.init(custom_reference=None, **kwargs)`

### Parameters
#### Function Parameters
- **custom_reference** (Optional[CustomReference | str]) - Optional - Set-up external reference (custom reference) dict for databook and tables. Format: `{'reference': [yml files], 'tables': [csv files]}`. Can be a string (YAML file path) or a dictionary.
- **kwargs** - Optional - Additional keyword arguments.
  - **mode** (Literal['silent', 'log', 'attach']) - Optional - Mode for time measurement logging. Default is 'log'.

### 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 = {'reference': [yml files], 'tables': [csv files]}`

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

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

### Response
#### Success Response
- Returns a ThermoDB object.

#### Response Example
```python
tdb = ptdb.init(custom_reference=custom_reference)
```
```

--------------------------------

### references property

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Gets the references dictionary.

```APIDOC
## references property

### Description
Gets the references dictionary.

### Returns
- **Dict[str, Any]** - A dictionary containing references.
```

--------------------------------

### Thermo.__init__(custom_ref=None, data_source='local')

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Create a database facade from bundled or custom reference data. Initializes the Thermo object with optional custom reference and data source label.

```APIDOC
## Thermo.__init__(custom_ref=None, data_source='local')

### Description
Create a database facade from bundled or custom reference data. Initializes the Thermo object with optional custom reference and data source label.

### Method
Constructor

### Signature
`__init__(self, custom_ref=None, data_source='local')`

### Parameters
- **custom_ref** (dict | str, optional) - Custom reference definition or reference path passed to `ManageData`.
- **data_source** (str, default='local') - Label describing the source used by the caller.

### Returns
None

### Notes
Custom-reference parsing and validation are delegated to `ManageData`.

### Source Code
```python
def __init__(
    self,
    custom_ref=None,
    data_source='local'
):
    """Create a database facade from bundled or custom reference data.

    Parameters
    ----------
    custom_ref : dict | str, optional
        Custom reference definition or reference path passed to ``ManageData``.
    data_source : str, default='local'
        Label describing the source used by the caller.

    Returns
    -------
    None

    Notes
    -----
    Custom-reference parsing and validation are delegated to ``ManageData``.
    """
    # NOTE: set
    self.data_source = data_source
    self.custom_ref = custom_ref

    # LINK: ManageData init
    ManageData.__init__(self, custom_ref=custom_ref)
```
```

--------------------------------

### CompBuilder.__init__

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Initializes a CompBuilder object with optional thermodb name and message. Sets up configuration and internal state.

```APIDOC
## CompBuilder.__init__

### Description
Initializes a CompBuilder object with optional thermodb name and message. Sets up configuration and internal state.

### Method
Constructor

### Signature
`__init__(thermodb_name=None, message=None)`

### Parameters
- **thermodb_name** (str, optional) - Name of the thermodb. Default is None.
- **message** (str, optional) - Message. Default is None.

### Source Code
```python
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)
    message : str
        message (default is None)
    '''
    # SECTION: get config
    config = get_config()
    # ! set build type
    self._build_type = config.build_type
    # ! set component identifiers
    self._component_name = config.component_name
    self._component_formula = config.component_formula
    self._component_state = config.component_state

    # SECTION: super init
    CompExporter.__init__(self)

    # NOTE: ensure a shared CompTools_ exists and attach to the instance
    if CompBuilder.CompTools_ is None:
        try:
            CompBuilder.CompTools_ = CompTools()
        except Exception:
            CompBuilder.CompTools_ = None

    # SECTION: set attributes
    # 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 = {}
```
```

--------------------------------

### CompBuilder.thermodb_name property

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Gets the thermodb name.

```APIDOC
## CompBuilder.thermodb_name property

### Description
Get thermodb name.

### Returns
- **str | None** - The thermodb name.
```

--------------------------------

### init(custom_reference=None, **kwargs)

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Initializes the thermodb app to check and build thermodynamic data and equations. Accepts an optional custom reference (dict or string) for databook and tables, and additional keyword arguments for logging mode.

```APIDOC
## init(custom_reference=None, **kwargs)

### Description
Initializes the thermodb app to check and build thermodynamic data and equations.

### Parameters
- **custom_reference** (Optional[CustomReference | str]) - Optional - Set-up external reference (custom reference) dict for databook and tables. Format: `{'reference': [yml files], 'tables': [csv files]}`.
- **kwargs** - Optional - Additional keyword arguments.
  - **mode** (Literal['silent', 'log', 'attach']) - Optional - Mode for time measurement logging. Default is 'log'.

### 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 = {'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)
```
```

--------------------------------

### get_component_data

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Gets component data from the database (api|local).

```APIDOC
## get_component_data

### Description
Get component data from database (api|local).

### Method
get_component_data

### Signature
get_component_data(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)

### Parameters
- **component_name** (str) - Required - Component name.
- **databook_id** (int) - Required - Databook id.
- **table_id** (int) - Required - Table id.
- **column_name** (Optional[str | list[str]]) - Optional - Column name.
- **dataframe** (bool) - Optional - Whether to return a dataframe.
- **query** (bool) - Optional - Query flag.
- **matrix_tb** (bool) - Optional - Matrix table flag.
- **component_state** (Optional[str]) - Optional - Component state.

### Returns
- **object** - Component data.
```

--------------------------------

### Initialize with YAML and External CSV Tables

Source: https://pythermodb.readthedocs.io/en/stable/custom-references/

Creates a custom reference with a YAML file and external CSV tables, initializes pyThermoDB, and prints the list of tables for the custom reference 'CUSTOM-REF-1'.

```python
import pyThermoDB as ptdb

ref = {
    "reference": ["path/to/ref1.yml"],
    "tables": [
        "path/to/General Data.csv",
        "path/to/Vapor Pressure.csv"
    ]
}
tdb = ptdb.init(custom_reference=ref)
print(tdb.list_tables("CUSTOM-REF-1", res_format="dict"))
```

--------------------------------

### ThermoReference.references (property)

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Gets the references dictionary containing all references.

```APIDOC
## ThermoReference.references (property)

### Description
Returns the references dictionary.

### Returns
- **Dict[str, Any]** - A dictionary containing references.

```

--------------------------------

### TableData.trans_data

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Property to get or set the stored transport-data payload.

```APIDOC
## TableData.trans_data

### Description
Property that returns the stored transport-data payload. The setter replaces the stored payload with the provided value.

### Method
Property Getter/Setter

### Parameters (Setter)
- **value** - Required - The new transport-data payload to store.
```

--------------------------------

### __init__(databook_name, table_name, table_data, matrix_table=None, matrix_symbol=None)

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Initializes matrix metadata, source data, and table structure. Accepts databook name, table name, table data dictionary, optional matrix table DataFrame, and optional matrix symbols list.

```APIDOC
## __init__(databook_name, table_name, table_data, matrix_table=None, matrix_symbol=None)

### Description
Initializes matrix metadata, source data, and table structure.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    databook_name: str | int,
    table_name: str | int,
    table_data,
    matrix_table=None,
    matrix_symbol: Optional[List[str]] = None
):
```

### Parameters
- **databook_name** (str | int) - Required - Name or identifier of the source databook.
- **table_name** (str | int) - Required - Name or identifier of the matrix table.
- **table_data** (dict) - Required - Matrix table definition and structure metadata.
- **matrix_table** (pandas.DataFrame, optional) - Optional - Matrix values for `VALUES` mode.
- **matrix_symbol** (list[str], optional) - Optional - Explicit matrix symbols overriding the source definition.

### Raises
- **TableMatrixDataFormatError** - If matrix-item keys use an invalid format.
- **TableMatrixDataStructureError** - If the table structure cannot be generated.

### Source Code
```python
def __init__(
    self,
    databook_name: str | int,
    table_name: str | int,
    table_data,
    matrix_table=None,
    matrix_symbol: Optional[List[str]] = None
):
    """Initialize matrix metadata, source data, and table structure.

    Parameters
    ----------
    databook_name : str | int
        Name or identifier of the source databook.
    table_name : str | int
        Name or identifier of the matrix table.
    table_data : dict
        Matrix table definition and structure metadata.
    matrix_table : pandas.DataFrame, optional
        Matrix values for ``VALUES`` mode.
    matrix_symbol : list[str], optional
        Explicit matrix symbols overriding the source definition.

    Raises
    ------
    TableMatrixDataFormatError
        If matrix-item keys use an invalid format.
    TableMatrixDataStructureError
        If the table structure cannot be generated.
    """
    # 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']

        # init
        self.__matrix_symbol = []

        # iterate through symbol_
        for item in symbol_:
            if isinstance(item, str):
                self.__matrix_symbol.append(item)
            elif isinstance(item, dict):
                # add values
                for key, value in item.items():
                    self.__matrix_symbol.append(value)

        # 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)
```
```

--------------------------------

### selected_tb (property)

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Gets or sets the currently selected table.

```APIDOC
## selected_tb (property)

### Description
Gets or sets the currently selected table.

### Method
property getter/setter

### Returns
- str: The stored table name or identifier.

### Setter Parameters
- **value** (str) - Required - Table name or identifier to retain as the current selection.
```

--------------------------------

### Initialize with YAML Reference Only

Source: https://pythermodb.readthedocs.io/en/stable/custom-references/

Creates a custom reference using only a YAML file and initializes pyThermoDB with it. Prints the list of databooks as a dictionary.

```python
import pyThermoDB as ptdb

ref = {
    "reference": ["path/to/source-ref-1.yml"]
}
tdb = ptdb.init(custom_reference=ref)
print(tdb.list_databooks(res_format="dict"))
```

--------------------------------

### selected_databook (property)

Source: https://pythermodb.readthedocs.io/en/stable/api-reference/

Gets or sets the currently selected databook.

```APIDOC
## selected_databook (property)

### Description
Gets or sets the currently selected databook.

### Method
property getter/setter

### Returns
- str: The stored databook name or identifier.

### Setter Parameters
- **value** (str) - Required - Databook name or identifier to retain as the current selection.
```

--------------------------------

### Import and Initialize pyThermoDB

Source: https://pythermodb.readthedocs.io/en/stable/comprehensive-walkthrough/

Imports pyThermoDB and rich, prints the version, and initializes the database object.

```python
import pyThermoDB as ptdb
from rich import print

print(ptdb.__version__)
tdb = ptdb.init()
```
Tokens:
Raw