libICEpost.src.base.dataStructures.Tabulation.OFTabulation ========================================================== .. py:module:: libICEpost.src.base.dataStructures.Tabulation.OFTabulation .. autoapi-nested-parse:: @author: F. Ramognino Last update: 12/06/2023 Attributes ---------- .. autoapisummary:: libICEpost.src.base.dataStructures.Tabulation.OFTabulation.to_pandas libICEpost.src.base.dataStructures.Tabulation.OFTabulation.merge Classes ------- .. autoapisummary:: libICEpost.src.base.dataStructures.Tabulation.OFTabulation._TableData libICEpost.src.base.dataStructures.Tabulation.OFTabulation._InputProps libICEpost.src.base.dataStructures.Tabulation.OFTabulation.OFTabulation Functions --------- .. autoapisummary:: libICEpost.src.base.dataStructures.Tabulation.OFTabulation.toPandas libICEpost.src.base.dataStructures.Tabulation.OFTabulation.concat libICEpost.src.base.dataStructures.Tabulation.OFTabulation.writeOFTable libICEpost.src.base.dataStructures.Tabulation.OFTabulation.sliceOFTable libICEpost.src.base.dataStructures.Tabulation.OFTabulation.clipOFTable libICEpost.src.base.dataStructures.Tabulation.OFTabulation.insertDimension libICEpost.src.base.dataStructures.Tabulation.OFTabulation.squeeze libICEpost.src.base.dataStructures.Tabulation.OFTabulation.plotOFTable libICEpost.src.base.dataStructures.Tabulation.OFTabulation.plotHeatmapOFTable Module Contents --------------- .. py:class:: _TableData Bases: :py:obj:`object` Dataclass storing the data for a tabulation .. py:attribute:: file :type: str The name of the file for I/O .. py:attribute:: table :type: libICEpost.src.base.dataStructures.Tabulation.Tabulation.Tabulation The tabulation .. py:method:: __eq__(value: object) -> bool .. py:class:: _InputProps Bases: :py:obj:`object` Dataclass storing properties for each input-variable .. py:attribute:: name :type: str The name used in the tablePropeties file .. py:attribute:: data :type: Iterable[float] The data-points .. py:method:: __post_init__() .. py:property:: numel .. py:method:: __eq__(value: object) -> bool .. py:function:: toPandas(table: OFTabulation) -> pandas.DataFrame Convert an instance of OFTabulation to a pandas.DataFrame with all the points stored in the tabulation. :param table: The OpenFOAM tabulation to convert to a dataframe. :type table: OFTabulation :returns: A dataframe with all the points stored in the tabulation. Columns for input and output variables :rtype: pd.DataFrame .. py:data:: to_pandas .. py:function:: concat(table: OFTabulation, *tables: OFTabulation, inplace: bool = False, verbose: bool = True, **kwargs) Extend the table with the data of other tables. The tables must have the same variables but not necessarily in the same order. The data of the second table is appended to the data of the first table, preserving the order of the variables. If fillValue is not given, the ranges of the second table must be consistent with those of the first table in the variables that are not concatenated. If fillValue is given, the missing sampling points are filled with the given value. :param table: The table to which the data is appended. :type table: OFTabulation :param \*tables: The tables to append. :type \*tables: OFTabulation :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :param verbose: Print information. Defaults to True. :type verbose: bool, optional :param \*\*kwargs: Keyword arguments to pass to the 'concat' method of the Tabulation objects. :keyword fillValue: The value to fill missing sampling points. Defaults to None. :kwtype fillValue: float, optional :keyword overwrite: If True, overwrite the data of the first table with the data of the second table in overlapping regions. Otherwise raise an error. Defaults to False. :kwtype overwrite: bool, optional :returns: The concatenated table if inplace is False, None otherwise. :rtype: OFTabulation|None .. py:data:: merge .. py:function:: writeOFTable(table: OFTabulation, path: str = None, *, binary: bool = False, overwrite: bool = False) Write the tabulation. Directory structure as follows: ``` path |-tableProperties |-constant | |-variable1 | |-variable2 | |-... |-system |-controlDict ``` :param table: The tabulation to write. :type table: OFTabulation :param path: Path where to save the table. In case not give, self.path is used. Defaults to None. :type path: str, optional :param binary: Writing in binary? Defaults to False. :type binary: bool, optional :param overwrite: Overwrite the table if found? Defaults to False. :type overwrite: bool, optional .. py:function:: sliceOFTable(table: OFTabulation, *, slices: Iterable[slice | Iterable[int] | int] = None, ranges: dict[str, float | Iterable[float]] = None, inplace=False, **argv) -> OFTabulation | None Extract a table with sliced datase. Can access in two ways: 1) by slicer 2) sub-set of interpolation points. Keyword arguments also accepred. For safety, the new table will not be writable and the path will be set to None. :param table: The table :type table: Tabulation :param slices: The slices to extract the table. Defaults to None. :type slices: Iterable[slice|Iterable[int]|int], optional :param ranges: The ranges to extract the table. Defaults to None. :type ranges: dict[str,float|Iterable[float]], optional :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :param \*\*argv: Keyword arguments to pass to the ranges. :returns: The sliced table if inplace is False, None otherwise. :rtype: OFTabulation|None .. py:function:: clipOFTable(table: OFTabulation, *, ranges: dict[str, tuple[float, float]] = None, inplace: bool = False, **kwargs) -> OFTabulation | None Clip the table to the given ranges. The ranges are given as a dictionary with the variable names as keys and a tuple with the minimum and maximum values. :param table: The table to clip. :type table: OFTabulation :param ranges: The ranges to clip for each input-variable. If min or max is None, the range is unbounded. :type ranges: dict[str,tuple[float|None,float|None]], optional :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :param \*\*kwargs: Can access also by keyword arguments. :returns: The clipped table if inplace is False, None otherwise. :rtype: OFTabulation|None .. py:function:: insertDimension(table: OFTabulation, *, variable: str, value: float, index: int = None, inplace: bool = False) -> OFTabulation | None Insert a new dimension in the table by adding a new variable with constant value. :param table: The table to insert the dimension. :type table: OFTabulation :param variable: The name of the input variable to insert. :type variable: str :param value: The value to assign to the new variable. :type value: float :param index: The index where to insert the new variable. Defaults to None (append at the end). :type index: int, optional :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :returns: The new table with the inserted dimension if inplace is False, None otherwise. :rtype: OFTabulation|None .. py:function:: squeeze(table: OFTabulation, *, inplace: bool = False) -> OFTabulation | None Remove dimensions with only one sampling point. :param table: The table to squeeze. :type table: OFTabulation :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :returns: The squeezed table if inplace is False, None otherwise. :rtype: OFTabulation|None .. py:function:: plotOFTable(table: OFTabulation, field: str, **kwargs) -> matplotlib.pyplot.Axes Plot a field of a tabulation. :param table: The tabulation to plot. :type table: OFTabulation :param field: The field to plot. :type field: str :param \*\*kwargs: Keyword arguments to pass to the 'plot' method of the Tabulation object. :returns: The axis where the plot is drawn. :rtype: plt.Axes .. py:function:: plotHeatmapOFTable(table: OFTabulation, field: str, **kwargs) -> matplotlib.pyplot.Axes Plot a heatmap of a field of a tabulation. :param table: The tabulation to plot. :type table: OFTabulation :param field: The field to plot. :type field: str :param \*\*kwargs: Keyword arguments to pass to the 'plotHeatmap' method of the Tabulation object. :returns: The axis where the plot is drawn. :rtype: plt.Axes .. py:class:: OFTabulation(ranges: dict[str, Iterable[float]], data: dict[str, Iterable[float]], *, path: str = None, order: Iterable[str], files: dict[str, str] = None, inputNames: dict[str, str] = None, outputNames: dict[str, str] = None, noWrite: bool = True, tablePropertiesParameters: dict[str, Any] = None, **kwargs) Bases: :py:obj:`libICEpost.src.base.dataStructures.Tabulation.BaseTabulation.BaseTabulation` Class used to store and handle an OpenFOAM tabulation (structured table). The tabulation is a multi-input multi-output, i.e., it access through a set of input variables (IV) to a set of tabulated variables (TV): [IV1, IV2, IV3, ...] -> [TV1, TV2, TV3, ...] .. py:attribute:: _path :type: str The path where the table is stored .. py:attribute:: _baseTableProperties :type: dict The additional data in the 'tableProperties' file apart from sampling points. .. py:attribute:: _data :type: dict[str, _TableData] The data stored in the tabulation .. py:attribute:: _inputVariables :type: dict[str, _InputProps] The properties of the input variables used to access the tabulation .. py:attribute:: _noWrite :type: bool Allow writing .. py:property:: path :type: str | None The path of the tabulation .. py:property:: tableProperties :type: dict[str:str] The table properties dictionary (read-only). .. py:property:: names :type: dict[str, str] Names to give at the variables found in the 'tableProperties' dictionary (read-only). .. py:property:: inputVariables :type: list[str] The input variables to access the tabulation (read-only). .. py:property:: fields :type: list[str] The fields tabulated. .. py:property:: ranges :type: dict[str, numpy.array[float]] The sampling points of the input variables to access the tabulation (read-only). .. py:property:: noWrite :type: bool Allow writing? .. py:property:: tables :type: dict[str, libICEpost.src.base.dataStructures.Tabulation.Tabulation.Tabulation | None] The tabulations for each variable (read-only). .. py:property:: files :type: dict[str, str] The name of the files where tables are saved (read-only). .. py:property:: size Returns the size of the table, i.e., the number of sampling points. .. py:property:: shape :type: tuple[int] The dimensions (dim1, dim2,..., dimn) of the tabulation. .. py:property:: ndim :type: int Returns the number of dimentsions of the table. .. py:method:: fromFile(path: str, order: Iterable[str] = None, *, inputNames: dict[str, str] = None, fields: Iterable[str] = None, outputNames: dict[str, str] = None, files: dict[str, str] = None, noRead: Iterable[str] = None, verbose: bool = True, **kwargs) -> OFTabulation :classmethod: Construct a table from files stored in an OpenFOAM-LibICE tabulation locted at 'path'. Directory structure as follows: \ path \ |-tableProperties \ |---constant \ | |-variable1 \ | |-variable2 \ | |-... \ |---system \ |-controlDict \ |-fvSchemes \ |-fvSolutions :param path: The master path where the tabulation is stored. :type path: str :param order: Nesting order of the input-variables used to access the tabulation. In case not given, lookup for entry 'inputVariables' in 'tableProperties' file. :type order: Iterable[str], optional :param inputNames: Renaming the input variables found in the 'tableProperties' file. Defaults to None. :type inputNames: dict[str,str], optional :param fields: The name of the fields to use for each output variable (by default, lookup for entry 'fields' in 'tableProperties' file). Defaults to None. :type fields: Iterable[str], optional :param outputNames: Renaming the output variables found in the 'tableProperties' file. Defaults to None. :type outputNames: dict[str,str], optional :param files: The name of the files to use for each output variable (by default, the name of the fields). Defaults to None. :type files: dict[str,str], optional :param noRead: Do not read the data of the given variables. Defaults to None. :type noRead: Iterable[str], optional :param verbose: Print information. Defaults to True. :type verbose: bool, optional :param \*\*kwargs: Optional keyword arguments of Tabulation.__init__ method of each Tabulation object. Kwargs: outOfBounds (Literal['fatal', 'clamp', 'extrapolate'], optional): Option to perform in case of out-of-bounds data (TODO). :returns: The tabulation loaded from files. :rtype: OFTabulation .. py:method:: from_pandas(data: pandas.DataFrame, order: Iterable[str], **kwargs) :classmethod: Construct a tabulation from a pandas DataFrame. :param data: The data to construct the tabulation. :type data: pd.DataFrame :param order: The order of the input-variables. :type order: Iterable[str] :param \*\*kwargs: Optional keyword arguments of OFTabulation.__init__ method. Kwargs: outOfBounds (Literal['fatal', 'clamp', 'extrapolate'], optional): Option to perform in case of out-of-bounds data (TODO). :returns: The tabulation constructed from the pandas DataFrame. :rtype: OFTabulation .. py:attribute:: fromPandas .. py:attribute:: _order The order in which the input variables are nested .. py:method:: checkDir() Check if all information required to read the tabulation are consistent and present in 'path'. Looking for: path path/constant path/tableProperties .. py:method:: copy() Return a copy of the tabulation. For safety, the new table will not be writable and the path will be set to None. .. py:attribute:: slice Extract a table with sliced data. Can access in two ways: 1) by slicer 2) sub-set of interpolation points. Keyword arguments also accepred. :param slices: The slicers for each input-variable. :type slices: Iterable[slice|Iterable[int]|int] :param ranges: Ranges of sliced table. Defaults to None. :type ranges: dict[str,float|Iterable[float]], optional :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :returns: The sliced table if inplace is False, None otherwise. :rtype: Self|None .. py:attribute:: clip Clip the table to the given ranges. The ranges are given as a dictionary with the variable names as keys and a tuple with the minimum and maximum values. :param ranges: The ranges to clip for each input-variable. If min or max is None, the range is unbounded. :type ranges: dict[str,tuple[float|None,float|None]], optional :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :param \*\*kwargs: Can access also by keyword arguments. :returns: The clipped table if inplace is False, None otherwise. :rtype: Self|None .. py:attribute:: write .. py:attribute:: insertDimension Insert an axis to the dimension-set of the table with a single value. This is useful to merge two tables with respect to an additional variable. :param table: The table to modify. :type table: BaseTabulation :param variable: The name of the variable to insert. :type variable: str :param value: The value for the range of the corresponding variable. :type value: float :param index: The index where to insert the variable in nesting order. If None, append the variable at the end. Defaults to None. :type index: int, optional :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :returns: The table with the inserted dimension if inplace is False, None otherwise. :rtype: BaseTabulation|None .. rubric:: Example Create a table with two variables: ``` >>> tab1 = Tabulation([1, 2, 3, 4], {"x":[0, 1], "y":[0, 1]}, ["x", "y"]) >>> tab1.insertDimension("z", 0.0, 1) >>> tab1.ranges {"x":[0, 1], "z":[0.0], "y":[0, 1]} ``` Create a second table with the same variables: ``` >>> tab2 = Tabulation([5, 6, 7, 8], {"x":[0, 1], "y":[0, 1]}, ["x", "y"]) >>> tab2.insertDimension("z", 1.0, 1) >>> tab2.ranges {"x":[0, 1], "z":[1.0], "y":[0, 1]} ``` Concatenate the two tables: ``` >>> tab1.concat(tab2, inplace=True) >>> tab1.ranges {"x":[0, 1], "z":[0.0, 1.0], "y":[0, 1]} ``` .. py:attribute:: squeeze Remove dimensions with only 1 data-point. :param inplace: If True, the operation is performed in-place. Defaults to False. :type inplace: bool, optional :returns: The squeezed tabulation if inplace is False, None otherwise. :rtype: Self|None .. py:attribute:: plot Plot the tabulation. .. py:attribute:: plotHeatmap Plot a heatmap of the tabulation. .. py:method:: clear() Clear the tabulation. .. py:method:: setFile(field: str, file: str) -> None Set the name of the file where to save the table of a field. :param field: The field to set the file-name of. :type field: str :param file: The name of the file. :type file: str .. py:method:: setTable(field: str, table: libICEpost.src.base.dataStructures.Tabulation.Tabulation.Tabulation | None) -> None Overwrite the table of a field. :param field: The field to set the file-name of. :type field: str :param file: The name of the file. :type file: str .. py:method:: addField(data: Iterable[float] | float | int | libICEpost.src.base.dataStructures.Tabulation.Tabulation.Tabulation | None, *, field: str, file: str = None, **kwargs) Add a new tabulated field (output variable). :param field: The name of the variable. :type field: str :param data: The data used to construct the tabulation. Defaults to None. :type data: Iterable | list[float] | float | Tabulation :param file: The name of the file for I/O. Defaults to None (same as 'field' value). :type file: str, optional :param \*\*kwargs: Keyword arguments for construction of each Tabulation object. .. py:method:: delField(field: str) Delete a field from the tabulation. :param field: The field to delete. :type field: str .. py:method:: setName(variable: str, name: str) -> None Set the name of a input-variable to use in the 'tableProperties' dictionary. :param variable: The input-variable to set the name of. :type variable: str :param name: The name of the input-variable. :type name: str .. py:method:: outOfBounds(field: str, method: str = None) -> str | None Get/set the out-of-bounds method for a field. :param field: The field to get/set the out-of-bounds method. :type field: str :param method: The method to set. Defaults to None. :type method: str, optional :returns: The out-of-bounds method for the field if method is not None, None otherwise. :rtype: str|None .. py:method:: setRange(variable: str, range: Iterable[float]) -> None Set the range of a variable. :param variable: The variable to set the range of. :type variable: str :param range: The range of the variable. :type range: Iterable[float] .. py:method:: _readTableProperties(*, inputNames: dict[str, str] = None, inputVariables: Iterable[str] = None, fields: Iterable[str] = None) -> Iterable[str] Read information stored in file 'path/tableProperties'. :param inputNames: The names to give to the input variables (optionally). Defaults to None. :type inputNames: dict[str,str], optional :param inputVariables: The input variables in correct nesting order. If not given, lookup for entry `inputVariables` in `tableProperties` file. Defaults to None. :type inputVariables: Iterable[str], optional :param fields: The names of the fields to use for each output variable (by default, lookup for entry `fields` in `tableProperties` file). Defaults to None. :type fields: Iterable[str], optional :returns: The names of the fields stored in the tabulation. :rtype: Iterable[str] .. py:method:: _readTable(fileName: str, tableName: str, *, verbose: bool = True, **kwargs) Read a tabulation from path/constant/fileName. :param fileName: The name of the file where the tabulation is stored. :type fileName: str :param tableName: The name to give to the loaded field in the tabulation. :type tableName: str :param verbose: Print information about the loading process. Defaults to True. :type verbose: bool, optional :param \*\*kwargs: Optional keyword arguments of Tabulation.__init__ method of each Tabulation object. :returns: self :rtype: Self .. py:method:: __getitem__(index: int | Iterable[int] | slice) -> dict[str, float] | dict[str, numpy.ndarray[float]] Get an element in the table. :param index: Either: - An index to access the table (flattened). - A tuple of the x,y,z,... indices to access the table. - A slice to access the table (flattened). - A tuple of slices to access the table. :type index: int | Iterable[int] | slice | Iterable[slice] :returns: The data stored in the table. - If a single index is given, a dictionary with the output variables at that index. - If slice|Iterable[slice] is given, a dictionary with the output variables at that slice. :rtype: dict[str,float]|dict[str,np.ndarray[float]] .. py:method:: __setitem__(index: int | Iterable[int] | slice, value: dict[str, float] | dict[str, numpy.ndarray[float]]) -> None :abstractmethod: Setting values in the table is not allowed. .. py:method:: __call__(table: str, *args, **kwargs) Interpolate from a specific table stored in the tabulation. :param table: The name of the table to use to interpolate the data. :type table: str :param \*args: Passed to the '__call__' method of the Tabulation instance to interpolate. :param \*\*kwargs: Passed to the '__call__' method of the Tabulation instance to interpolate. :returns: The interpolated data from the specified table. :rtype: float|np.ndarray[float] .. py:method:: __eq__(value: OFTabulation) -> bool .. py:method:: __repr__() .. py:method:: __str__()