Model tool

model_tool

Attributes

Classes

ModelCreationTool

ModelCreationTool(
    root_directory: str | Path = root_directory,
    directory_naming_method: DirectoryNamingMethod = NUMBERED,
    working_directory: str | Path = working_directory,
    **options
)

Bases: BaseAnalysisTool

A tool to create a model and set its default values.

Examples:

>>> from vimseo.tools.example_tool import MyTool
>>> tool = MyTool()
>>> tool.execute()
>>> print(tool.result)
# The result can be saved on disk.
>>> tool.save_results()
# Optionnaly, the current options of the tool can be saved on disk.
>>> tool.result.save_metadata_to_disk()
# The result saved on disk can be loaded.
>>> results = BaseTool.load_results(tool.working_directory /
>>> 'Tool_result.pickle')
# Then, the tool can plot the result. Note that the :meth:`plot_results` method
# takes the result as input. In the future, this method will be moved from the
# tools to a post processor class.
>>> tool.plot_results(results, save=True, show=False)

TODO allow passing pydantic model

Parameters:

• root_directory (str | Path, default: root_directory ) –

  The description is missing.

• directory_naming_method (DirectoryNamingMethod, default: NUMBERED ) –

  The description is missing.

• working_directory (str | Path, default: working_directory ) –

  The description is missing.

• **options –

  The description is missing.

Source code in src/vimseo/tools/model_tool.py

def __init__(
    self,
    root_directory: str | Path = config.root_directory,
    directory_naming_method: DirectoryNamingMethod = DirectoryNamingMethod.NUMBERED,
    working_directory: str | Path = config.working_directory,
    **options,
):
    super().__init__(
        root_directory=root_directory,
        directory_naming_method=directory_naming_method,
        working_directory=working_directory,
        **options,
    )
    self.result = ModelResult()

Attributes

grammar property

grammar

The validation grammar.

option_names property

option_names

The names of the options that can be passed to execute().

options property

options

The options of the tool.

results instance-attribute

results: BaseResult | None

The results of the tool.

Functions

execute

execute(
    settings=ModelCreationSettings, **options
) -> ModelResult

The user-defined treatment called by :meth:execute.

Parameters:

• options –

  The options of the execution.

Source code in src/vimseo/tools/model_tool.py

@BaseCompositeTool.validate
def execute(self, settings=ModelCreationSettings, **options) -> ModelResult:
    model = create_model(options["name"], options["load_case"])
    model.default_input_data.update({
        name: array(value) for name, value in options["default_inputs"].items()
    })
    self.result.model = model

load_options_from_metadata

load_options_from_metadata(
    file_path: str | Path | None = None,
)

Load a result of a tool from the disk.

Parameters:

• file_path (str | Path | None, default: None ) –

  The path to the file.

Source code in src/vimseo/tools/base_tool.py

def load_options_from_metadata(self, file_path: str | Path | None = None):
    """Load a result of a tool from the disk.

    Args:
        file_path: The path to the file.
    """
    file_path = (
        self._working_directory / f"{self.result.__class__.__name__}_metadata.json"
        if file_path is None
        else file_path
    )
    with Path(file_path).open() as f:
        loaded_metadata = json.load(f)
        if ToolResultMetadata._OPTIONS_KEY not in loaded_metadata:
            msg = f"Loaded options must contain the key '{ToolResultMetadata._OPTIONS_KEY}'"
            raise KeyError(msg)
        loaded_options = loaded_metadata[ToolResultMetadata._OPTIONS_KEY]
        if self._has_check_options:
            self._check_options(**loaded_options)
        self._options.update(loaded_options)

load_results classmethod

load_results(path: Path)

Load a result of a tool from the disk.

For a JSON file, only SpaceToolResult is supported. This method must be called from class SpaceTool. JSON format for tool results is deprecated.

Parameters:

• path (Path) –

  The path to the file.

• tool_name –

  The name of the tool associated with the result under stored

Source code in src/vimseo/tools/base_tool.py

@classmethod
def load_results(cls, path: Path):
    """Load a result of a tool from the disk.

    For a `JSON` file, only `SpaceToolResult` is supported.
    This method must be called from class `SpaceTool`.
    `JSON` format for tool results is deprecated.

    Args:
        path: The path to the file.
        tool_name: The name of the tool associated with the result under stored
        in ``path``.
    """
    import h5py

    path = Path(path)
    if path.suffix == ".hdf5":
        class_name = ""
        with h5py.File(path, "r") as f:
            class_name = f.attrs["__class__"]
        tmp_result = ToolResultsFactory().create(class_name)
        return type(tmp_result).from_hdf5(path)
    # TODO remove support for json
    if path.suffix == ".json":
        if cls.__name__ == "BaseTool":
            msg = (
                "Loading tool result from JSON format requires to call "
                "load_results from the tool class associated with the result stored "
                "in the JSON file."
            )
            raise ValueError(msg)
        LOGGER.warning("Loading tool results from JSON format is deprecated.")
        io = IOFactory().create(f"{cls.__name__}FileIO")
        return io.read(
            file_name=path,
        )
    if path.suffix == ".pickle":
        with Path(path).open("rb") as f:
            return pickle.load(f)

    msg = f"Unknow file format {path.suffix}. Supported formats are {cls._RESULT_FORMATS}"
    raise ValueError(msg)

plot_results

plot_results(
    result: ModelResult,
    directory_path: str | Path = "",
    save=False,
    show=True,
    **options
) -> Mapping[str, Figure]

Plot criteria for a given variable name.

Parameters:

• result (ModelResult) –

  The result of the tool.

• directory_path (str | Path, default: '' ) –

  The path under which the plots are saved.

• save –

  Whether to save the plot on disk.

• show –

  Whether to show the plot.

• **options –

  The description is missing.

Source code in src/vimseo/tools/model_tool.py

def plot_results(
    self,
    result: ModelResult,
    directory_path: str | Path = "",
    save=False,
    show=True,
    **options,
) -> Mapping[str, Figure]:
    working_directory = (
        self.working_directory if directory_path == "" else Path(directory_path)
    )
    return self.result.model.plot_results(
        directory_path=working_directory,
        save=save,
        show=show,
    )

save_results

save_results(
    prefix: str = "", file_format: str = "hdf5"
) -> None

Save the results of the tool on disk. The file path is BaseTool.working_directory / {filename}_result.{file_format}.

Args: prefix: The prefix of the filename result.

Parameters:

• prefix (str, default: '' ) –

  The description is missing.

• file_format (str, default: 'hdf5' ) –

  The description is missing.

Source code in src/vimseo/tools/base_composite_tool.py

def save_results(self, prefix: str = "", file_format: str = "hdf5") -> None:
    super().save_results(prefix, file_format=file_format)
    for tool in self._subtools.values():
        tool.save_results(prefix, file_format=file_format)

set_plot

set_plot(class_name, **options) -> None

Set the type of plot to show the results of this tool.

Parameters:

• class_name –

  The name of the plot class.

• **options –

  The options of the plot constructor.

Source code in src/vimseo/tools/base_tool.py

def set_plot(self, class_name, **options) -> None:
    """Set the type of plot to show the results of this tool.

    Args:
        class_name: The name of the plot class.
        **options: The options of the plot constructor.
    """
    if self._plot_factory:
        self._plot = self._plot_factory.create(class_name, **options)
    self._plot_class = class_name

ModelResult dataclass

ModelResult(metadata: ToolResultMetadata | None = None)

Bases: BaseResult

A result of a tool (:class:.BaseTool).

This result is the object that flows through a workflow of tools. It is self-supporting and carries information on how to process it through the :attr:.ToolResultMetadata.settings. The result can be written on disk in binary format (pickle) and its metadata can also be written on disk in a readable format (json).

Attributes

metadata class-attribute instance-attribute

metadata: ToolResultMetadata | None = None

ToolResultMetadata attached to a result.

Functions

from_hdf5 classmethod

from_hdf5(path: str | Path)

Deserialize from a file path.

Source code in src/vimseo/tools/base_result.py

@classmethod
def from_hdf5(cls, path: str | Path):
    """Deserialize from a file path."""
    with h5py.File(path, "r") as f:
        return cls._from_hdf5_file(f)

from_hdf5_buffer classmethod

from_hdf5_buffer(buffer: IOBase | bytes)

Deserialize from a file-like object or bytes (e.g. Streamlit uploader).

Source code in src/vimseo/tools/base_result.py

@classmethod
def from_hdf5_buffer(cls, buffer: IOBase | bytes):
    """Deserialize from a file-like object or bytes (e.g. Streamlit uploader)."""
    if isinstance(buffer, bytes):
        buffer = BytesIO(buffer)
    else:
        buffer.seek(0)
    with h5py.File(BytesIO(buffer.read()), "r") as f:
        return cls._from_hdf5_file(f)

save_metadata_to_disk

save_metadata_to_disk(file_path: Path | str = '')

Save metadata to disk in a readable format.

Source code in src/vimseo/tools/base_result.py

def save_metadata_to_disk(self, file_path: Path | str = ""):
    """Save metadata to disk in a readable format."""
    file_path = Path.cwd() if file_path == "" else Path(file_path)
    with Path(file_path / f"{self.__class__.__name__}_metadata.json").open(
        "w"
    ) as f:
        json.dump(asdict(self.metadata), f, indent=4, ensure_ascii=True)

to_hdf5

to_hdf5(path: str | Path) -> None

Serialize a BaseResult into an HDF5 file.

The file can be explored with an on-line reader, like https://myhdf5.hdfgroup.org/. For more information about hdf5, see HDF5 documentation.

Source code in src/vimseo/tools/base_result.py

def to_hdf5(self, path: str | Path) -> None:
    """Serialize a BaseResult into an HDF5 file.

    The file can be explored with an on-line reader,
    like <https://myhdf5.hdfgroup.org/>.
    For more information about hdf5, see
    [HDF5 documentation](https://docs.hdfgroup.org/hdf5/develop/)."""
    with h5py.File(path, "w") as f:
        f.attrs["__class__"] = type(self).__name__
        for fld in fields(self):
            serialize_value(f, fld.name, getattr(self, fld.name))

to_hdf5_buffer

to_hdf5_buffer() -> BytesIO

Serialize a BaseResult into an HDF5 buffer.

Source code in src/vimseo/tools/base_result.py

def to_hdf5_buffer(self) -> BytesIO:
    """Serialize a BaseResult into an HDF5 buffer."""
    bio = BytesIO()
    with h5py.File(bio, "w") as f:
        f.attrs["__class__"] = type(self).__name__
        for fld in fields(self):
            serialize_value(f, fld.name, getattr(self, fld.name))

    return bio

to_pickle

to_pickle(file_path: str | Path)

Save result instance to disk.

Source code in src/vimseo/tools/base_result.py

def to_pickle(self, file_path: str | Path):
    """Save result instance to disk."""
    with Path(file_path).open("wb") as f:
        pickle.dump(self, f)

Functions