multiphasepy 4.0.0__py3-none-any.whl

multiphasepy/__init__.py

@@ -0,0 +1,30 @@
+# Multiphase Python Repository by HZDR
+#
+# SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Dresden-Rossendorf e.V. (HZDR)
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Mark this directory as multiphasepy Python package.
+
+Attributes:
+    pkgversion (str): Installed version of the package
+"""
+
+from importlib.metadata import version as get_installed_version
+
+from packaging.version import Version
+
+pkgversion = get_installed_version(str(__package__))
+
+
+def minimum_version(minversion: str):
+    """Check that the installed version meets the minimum required version.
+
+    Args:
+        minversion: Minimum required version.
+    """
+    if Version(pkgversion) < Version(minversion):
+        raise RuntimeError(
+            f"{__package__} >= {minversion} is required, "
+            f"but version {pkgversion} is installed."
+        )

multiphasepy/assets/header_templates/c++_foundation.jinja

@@ -0,0 +1,30 @@
+/*--------------------------------{{file_type}}----------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     | Website:  https://openfoam.org
+    \\  /    A nd           | Copyright (C) {% for org in copyrightHolder %}{% if org.name == "OpenFOAM Foundation" %}{{- org.year -}}{% endif %}{% endfor %} OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+{% for category, text in header.items() -%}
+{{ category }}
+    {{ text | wordwrap(76, wrapstring='\n    ', break_long_words=False)  | replace('\n    \n', '\n\n') }}
+
+{% endfor -%}
+\*---------------------------------------------------------------------------*/
+{# Keep a tailing new line to separate body from header #}

multiphasepy/assets/header_templates/c++_hzdr.jinja

@@ -0,0 +1,46 @@
+/*--------------------------------{{file_type}}----------------------------------*\
+  ==  == ====== ====   ====    |
+                    \\     ||  | {{name | truncate(47, True, '...') }}
+  ======   //   ||  || ===//   | Website: {{url}}
+  ||  ||  //    ||  // || \\   | License: GPL-3.0-or-later
+  ==  == ====== ====   ==  ==  |
+-------------------------------------------------------------------------------
+License
+{%- filter wordwrap(76, wrapstring='\n    ', break_long_words=False) | replace('\n    \n', '\n\n') %}
+This file is part of the {{name}}.
+{% for org in copyrightHolder %}
+Copyright (C) {{ org.year }} by {{ org.name }}, Website: {{ org.url }}
+{% endfor %}
+{% filter replace('\n', ' ')-%}
+If you are interested in which files are original OpenFOAM Foundation files,
+which OpenFOAM Foundation files were modified, and which files were newly
+created, see FILES.md.
+{%- endfilter %}
+banana
+
+{% filter replace('\n', ' ')-%}
+{{name}} is free software: you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+{%- endfilter %}
+
+{% filter replace('\n', ' ')-%}
+{{name}} is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+{%- endfilter %}
+
+{% filter replace('\n', ' ')-%}
+You should have received a copy of the GNU General Public License along with
+the {{name}}. If not, see <http://www.gnu.org/licenses/>.
+{%- endfilter %}
+{% endfilter %}
+
+{% for category, text in header.items() -%}
+{{ category }}
+    {{ text | wordwrap(76, wrapstring='\n    ', break_long_words=False) | replace('\n    \n', '\n\n') }}
+
+{% endfor -%}
+\*---------------------------------------------------------------------------*/
+{# Keep a tailing new line to separate body from header #}

multiphasepy/assets/header_templates/config_openfoam_foundation.jinja

@@ -0,0 +1,17 @@
+/*--------------------------------{{file_type}}----------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     | Website:  https://openfoam.org
+    \\  /    A nd           | Version:  dev
+     \\/     M anipulation  |
+{% if header -%}
+{% for category, text in header.items() -%}
+{% if loop.first -%}
+-------------------------------------------------------------------------------
+{%- endif %}
+{{ category }}
+    {{ text | wordwrap(76, wrapstring='\n    ', break_long_words=False)  | replace('\n    \n', '\n\n') }}
+
+{% endfor %}
+{% endif -%}
+\*---------------------------------------------------------------------------*/

multiphasepy/assets/header_templates/config_openfoam_hzdr.jinja

@@ -0,0 +1,17 @@
+/*--------------------------------{{file_type}}----------------------------------*\
+  ==  == ====== ====   ====    |
+                    \\     ||  | {{name | truncate(47, True, '...') }}
+  ======   //   ||  || ===//   | Website: {{url}}
+  ||  ||  //    ||  // || \\   | License: GPL-3.0-or-later
+  ==  == ====== ====   ==  ==  |
+{% if header -%}
+{% for category, text in header.items() -%}
+{% if loop.first -%}
+-------------------------------------------------------------------------------
+{%- endif %}
+{{ category }}
+    {{ text | wordwrap(76, wrapstring='\n    ', break_long_words=False)  | replace('\n    \n', '\n\n') }}
+
+{% endfor -%}
+{% endif -%}
+\*---------------------------------------------------------------------------*/

multiphasepy/assets/header_templates/shell_foundation.jinja

@@ -0,0 +1,35 @@
+{% if shebang -%}
+{{ shebang }}
+#---------------------------------{{file_type}}------------------------------------
+{%- else -%}
+#---------------------------------{{file_type}}------------------------------------
+{%- endif %}
+# =========                 |
+# \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+#  \\    /   O peration     | Website:  https://openfoam.org
+#   \\  /    A nd           | Copyright (C) {% for org in copyrightHolder %}{% if org.name == "OpenFOAM Foundation" %}{{- org.year -}}{% endif %}{% endfor %} OpenFOAM Foundation
+#    \\/     M anipulation  |
+#------------------------------------------------------------------------------
+# License
+#     This file is part of OpenFOAM.
+#
+#     OpenFOAM is free software: you can redistribute it and/or modify it
+#     under the terms of the GNU General Public License as published by
+#     the Free Software Foundation, either version 3 of the License, or
+#     (at your option) any later version.
+#
+#     OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+#     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+#     for more details.
+#
+#     You should have received a copy of the GNU General Public License
+#     along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+#
+{% for category, text in header.items() -%}
+{{ category | indent(width='# ', first=True) }}
+#     {{ text | wordwrap(74, wrapstring='\n#     ', break_long_words=False) }}
+#
+{% endfor -%}
+#------------------------------------------------------------------------------
+{# Keep a tailing new line to separate body from header #}

multiphasepy/assets/header_templates/shell_hzdr.jinja

@@ -0,0 +1,50 @@
+{% if shebang -%}
+{{ shebang }}
+#---------------------------------{{file_type}}------------------------------------
+{%- else -%}
+#---------------------------------{{file_type}}------------------------------------
+{%- endif %}
+# ==  == ====== ====   ====    |
+#                   \\     ||  | {{name | truncate(47, True, '...') }}
+# ======   //   ||  || ===//   | Website: {{url}}
+# ||  ||  //    ||  // || \\   | License: GPL-3.0-or-later
+# ==  == ====== ====   ==  ==  |
+#------------------------------------------------------------------------------
+# License
+{%- filter wordwrap(74, wrapstring='\n#     ', break_long_words=False) %}
+This file is part of the {{name}}.
+{% for org in copyrightHolder %}
+Copyright (C) {{ org.year }} by {{ org.name }}, Website: {{ org.url }}
+{% endfor %}
+{% filter replace('\n', ' ')-%}
+If you are interested in which files are original OpenFOAM Foundation files,
+which OpenFOAM Foundation files were modified, and which files were newly
+created, see FILES.md.
+{%- endfilter %}
+
+{% filter replace('\n', ' ')-%}
+{{name}} is free software: you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+{%- endfilter %}
+
+{% filter replace('\n', ' ')-%}
+{{name}} is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+{%- endfilter %}
+
+{% filter replace('\n', ' ')-%}
+You should have received a copy of the GNU General Public License along with
+the {{name}}. If not, see <http://www.gnu.org/licenses/>.
+{%- endfilter %}
+{% endfilter %}
+#
+{% for category, text in header.items() -%}
+{{ category | indent(width='# ', first=True) }}
+#     {{ text | wordwrap(74, wrapstring='\n#     ', break_long_words=False) }}
+#
+{% endfor -%}
+#------------------------------------------------------------------------------
+{# Keep a tailing new line to separate body from header #}

multiphasepy/auxiliary.py

@@ -0,0 +1,423 @@
+# Multiphase Python Repository by HZDR
+#
+# SPDX-FileCopyrightText: 2026 Helmholtz-Zentrum Dresden-Rossendorf e.V. (HZDR)
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Module containing common functions for system operations."""
+
+import subprocess
+from difflib import SequenceMatcher
+from functools import partial
+from importlib.metadata import metadata
+from pathlib import Path
+from typing import Callable, Dict, List, Tuple
+
+import dask.bag as db
+from fabric import Connection
+from invoke.exceptions import UnexpectedExit
+from jinja2 import Environment, FileSystemLoader, meta
+
+from .exceptions import FileIdentificationError
+from .io import DictContainer, filetags
+from .logutils import log
+
+
+def project_urls() -> dict:
+    """Retrieve the project URLs from the package metadata.
+
+    Returns:
+        A dictionary containing the project URLs or an empty dictionary if no
+        URLs are found.
+    """
+    urls = metadata("multiphasepy").get_all("Project-URL")
+
+    if urls is not None:
+        return dict(url.split(", ", 1) for url in urls)
+    else:
+        return {}
+
+
+def runcommand(
+    cmd: List[str],
+    host: str = "localhost",
+    raise_on_error: bool = True,
+    hide: bool = True,
+    warn: bool = True,
+) -> Tuple[int, str | None]:
+    """Execute a command locally or on a remote host.
+
+    The given command is executed either locally if host is 'localhost', or on
+    the specified remote host using SSH. The function returns a tuple of the
+    exit code and stdout obtained from command execution.
+
+    Args:
+        cmd: command sequence as a list.
+        host: 'localhost' or a remote host.
+        raise_on_error: raise subprocess.CalledProcessError or
+                        UnexpectedExit.
+        hide: for remote runs, whether to hide output
+        warn: add warning to logger in case an error occurs
+
+    Returns:
+        exit code and stdout obtained from command execution.
+    """
+    # Local execution
+    if host == "localhost":
+        try:
+            log.debug(f"Running command locally: '{' '.join(cmd)}'")
+            # cmd is expected to be a list of argv elements
+            res = subprocess.run(
+                cmd,
+                text=hide,
+                capture_output=hide,
+                check=raise_on_error,
+            )
+            return (res.returncode, res.stdout)
+        except subprocess.CalledProcessError as e:
+            msg = f"Command '{cmd}' failed with exit code {e.returncode}"
+            if raise_on_error:
+                log.error(msg)
+                raise
+            elif warn:
+                log.warning(msg)
+        except FileNotFoundError as e:
+            msg = f"Command '{cmd}' not found: {e}"
+            if raise_on_error:
+                log.error(msg)
+                raise
+            elif warn:
+                log.warning(msg)
+    # Remote execution
+    else:
+        try:
+            log.debug(f"Running command on {host}: {' '.join(cmd)}")
+            with Connection(host) as c:
+                remote_cmd = " ".join(map(str, cmd))
+                res = c.run(remote_cmd, hide=hide, warn=not raise_on_error)
+                return (res.exited, res.stdout)
+        except UnexpectedExit as e:
+            msg = f"Command '{cmd}' failed with exit code {e.result.exited}"
+            if raise_on_error:
+                log.error(msg)
+                log.debug(f"stderr: {e.result.stderr}")
+                raise
+            else:
+                log.warning(msg)
+
+    return (1, None)
+
+
+def osname(host: str = "localhost") -> str:
+    """Get name of operating system.
+
+    Args:
+        host: hostname or IP address of the remote host (default: localhost)
+
+    Returns:
+        Name of the operating system, e.g., darwin or linux
+    """
+    _, stdout = runcommand(["uname", "-s"], host=host)
+    if stdout is not None:
+        osname = stdout.strip().lower()
+    else:
+        osname = "unknown"
+    log.debug(f"Operating system: {osname}")
+
+    return osname
+
+
+def hostname(host: str = "localhost") -> str:
+    """Get name of the host system in network.
+
+    Args:
+        host: hostname or IP address of the remote host (default: localhost)
+
+    Returns:
+        Hostname
+    """
+    _, stdout = runcommand(["hostname"], host=host)
+    if stdout is not None:
+        hostname = stdout.strip()
+    else:
+        hostname = "unknown"
+    log.debug(f"Hostname: {hostname}")
+    return hostname
+
+
+def userinfo(host: str = "localhost") -> dict:
+    """Get user-specific information from host.
+
+    Args:
+        host: hostname or IP address of the remote host (default: localhost)
+
+    Returns:
+        Dictionary with user information (username, userid, groupname, groupid,
+        home)
+    """
+    _exit_code, stdout = runcommand(["id", "-u"], host=host)
+    if stdout is not None:
+        uid = stdout.strip()
+    else:
+        uid = "unknown"
+
+    _exit_code, stdout = runcommand(["id", "-g"], host=host)
+    if stdout is not None:
+        gid = stdout.strip()
+    else:
+        gid = "unknown"
+
+    _exit_code, stdout = runcommand(["id", "-un"], host=host)
+    if stdout is not None:
+        uname = stdout.strip()
+    else:
+        uname = "unknown"
+
+    _exit_code, stdout = runcommand(["id", "-gn"], host=host)
+    if stdout is not None:
+        gname = stdout.strip()
+    else:
+        gname = "unknown"
+
+    _exit_code, stdout = runcommand(["echo", "$HOME"], host=host)
+    if stdout is not None:
+        home = stdout.strip()
+    else:
+        home = "unknown"
+
+    log.debug(f"User info: {uname} ({uid}), {gname} ({gid}), {home}")
+
+    return {
+        "username": uname,
+        "userid": uid,
+        "groupname": gname,
+        "groupid": gid,
+        "home": home,
+    }
+
+
+def run_parallel_on_files(
+    func: Callable, flist: List[str], ntask: int, fkwargs: dict | None = None
+):
+    """Run function for all files in a list in parallel.
+
+    Wrapper function to run a callable for all files in a list in parallel.
+    The function uses dask to manage parallel execution. The function is
+    optimized to use ntask in parallel, or the number of files, if the number
+    is less than the given ntasks. The function is optimized for job running
+    independently on each file.
+
+    Args:
+        func: Callable that accepts a filename as first positional argument.
+        flist: Iterable of filenames.
+        ntask: Maximum number of partitions / parallel workers to use.
+        fkwargs: Optional dict of keyword arguments forwarded to `func`.
+
+    Returns:
+        A list with results from all calls (order follows input sequence).
+    """
+    npartitions = min(len(flist), max(1, int(ntask)))
+    log.info(f"Running on {npartitions} partitions in parallel.")
+
+    # Create dask bag and map the callable. If func_kwargs are given, bind
+    # them with functools.partial. The resulting callable receives the
+    # filename as the first argument when mapped over the bag.
+    b = db.from_sequence(flist, npartitions=npartitions)
+    if fkwargs:
+        mapped_callable = partial(func, **fkwargs)
+    else:
+        mapped_callable = func
+
+    results = b.map(mapped_callable).compute()
+    return results
+
+
+def run_serial_on_files(
+    func: Callable, flist: List[str] | List[Path], fkwargs: dict | None = None
+):
+    """Run function for all files in a list in serial.
+
+    Wrapper function to run a callable for all files in a list in serial.
+
+    Args:
+        func: Callable that accepts a filename as first positional argument.
+        flist: Iterable of filenames.
+        fkwargs: Optional dict of keyword arguments forwarded to `func`.
+
+    Returns:
+        A list with results from all calls (order follows input sequence).
+    """
+    results = []
+    for filename in flist:
+        if fkwargs:
+            result = func(filename, **fkwargs)
+        else:
+            result = func(filename)
+        results.append(result)
+    return results
+
+
+def merge_dicts_by_key(
+    dicts: list[dict], key: str = "name", threshold: float = 0.85
+) -> list[dict]:
+    """Group and deduplicate a list of dictionaries by fuzzy-matching a key.
+
+    Uses the standard library's difflib.SequenceMatcher to compute a similarity
+    ratio between key values. Dictionaries with a similarity ratio
+    greater or equal to `threshold` are considered duplicates and are merged.
+
+    Args:
+        dicts: List of dictionaries to deduplicate.
+        key: Key in the dictionaries to compare (default: 'name').
+        threshold: Similarity threshold in range [0, 1] (default: 0.85).
+
+    Returns:
+        A list of merged dictionaries (order of first appearance).
+    """
+    # Prepare name list safely (use .get to avoid KeyError) and normalize inline
+    names = [d.get(key, "") if isinstance(d, dict) else "" for d in dicts]
+    norm = [str(n).lower().strip() for n in names]
+
+    result: list[dict] = []
+    used = set()
+
+    # Loop over normalized keys in original order
+    for i, n in enumerate(norm):
+        if i in used:
+            continue
+
+        # Collect all indices with similar (non-empty) keys
+        group = [
+            j
+            for j in range(len(norm))
+            if j not in used
+            and norm[j]
+            and SequenceMatcher(None, n, norm[j]).ratio() >= threshold
+        ]
+
+        # Merge dictionaries with similar keys, keep first occurrence's values
+        # when keys conflict
+        merged: dict = {}
+        log.debug(f"Merging keys: {', '.join([names[idx] for idx in group])}")
+
+        for idx in group:
+            for k, v in dicts[idx].items():
+                merged.setdefault(k, v)
+
+        result.append(merged)
+        used.update(group)
+
+    return result
+
+
+def filter_tags_from_file_list(
+    flist: list[Path],
+    tags: list[str] | None = None,
+    tags_or: list[str] | None = None,
+) -> tuple[list[Path], list[str]]:
+    """Filter filelist according to file tags.
+
+    The file tags are checked with the io.filetags function. The tags
+    returned are compared to the tags defined the tags list. If all tags match
+    the file is added to the result list. In case no filter types are given,
+    all files are returned.
+
+    Args:
+        flist: List of filenames to filter.
+        tags: List of tags that must be present.
+        tags_or: List of tags where at least one must be present.
+
+    Returns:
+        Two lists, one list of matching files, and a second one with
+        corresponding tags.
+    """
+    results = []
+    restags = []
+
+    log.debug(f"Filtering files by tags: {tags} (AND), {tags_or} (OR)")
+
+    for f in flist:
+        try:
+            ftags = filetags(f)
+        except FileIdentificationError as e:
+            log.warning(f"{e}")
+            continue
+
+        # NO filter condition: add all files
+        if not tags and not tags_or:
+            results.append(f)
+            restags.append(ftags)
+            continue
+
+        # AND condition: all tags must be present
+        if tags:
+            if set(tags) <= ftags:
+                results.append(f)
+                restags.append(ftags)
+                continue
+
+        # OR condition: at least one tag must be present
+        if tags_or:
+            if set(tags_or) & ftags:
+                results.append(f)
+                restags.append(ftags)
+                continue
+
+    return (results, restags)
+
+
+def validate_template_variables(template: str, keys: set) -> None:
+    """Check if all variables required for rendering a template are present.
+
+    The function makes sure that all variables required to render the template
+    are present as a key in the data dictionary.
+
+    Args:
+        template: template to render with Jinja.
+        keys: keys in the data dictionary.
+
+    Raises:
+        KeyError: Lists the missing keys if variables are missing.
+    """
+    env = Environment()
+    required_variables = meta.find_undeclared_variables(env.parse(template))
+
+    missing = required_variables - keys
+    if missing:
+        error_msg = (
+            f"Missing variables for template: {', '.join(sorted(missing))}"
+        )
+        raise KeyError(error_msg)
+
+
+def render_jinja_template(
+    tpname: str,
+    tpdir: Path,
+    tpdata: Dict | DictContainer,
+    validate: bool = True,
+) -> str:
+    """Render a given Jinja template.
+
+    The function looks for a Jinja template in a template directory. The
+    template is then rendered with the given data.
+
+    Args:
+        tpname: name of the header template.
+        tpdir: directory containing the template.
+        tpdata: data to render the template with.
+        validate: check the template data before rendering.
+
+    Returns:
+        A str with the rendered header.
+    """
+    env = Environment(
+        loader=FileSystemLoader(tpdir), keep_trailing_newline=True
+    )
+    template = env.get_template(tpname)
+
+    if validate:
+        source, _, _ = env.loader.get_source(env, tpname)
+        validate_template_variables(source, set(tpdata.keys()))
+
+    log.debug(f"Rendering template '{tpname}' with data: {tpdata}")
+    return template.render(tpdata)