pyrbd 0.2.5__py3-none-any.whl

pyrbd/__init__.py

@@ -0,0 +1,11 @@
+"""Package for creating simple reliability block diagrams using LaTeX TikZ."""
+
+from .block import Block, Series, Group
+from .diagram import Diagram
+
+__all__ = [
+    "Block",
+    "Series",
+    "Group",
+    "Diagram",
+]

pyrbd/block.py

@@ -0,0 +1,456 @@
+"""Module containing Block, Series and Group class definitions."""
+
+from typing import Optional
+from itertools import combinations
+from copy import deepcopy
+
+
+class Block:
+    """Block entering a reliability block diagram.
+
+    Parameters
+    ----------
+    text : str
+        block text string
+    color : str
+        block color
+    parent : Optional[Block]
+        parent `Block` instance
+    shift : tuple[float, float], optional
+        additional position shift `(x, y)` relative to `parent` `Block` instance
+
+    Attributes
+    ----------
+    tikz_options : str
+        TikZ node formatting options
+
+
+    Examples
+    --------
+    >>> block_1 = Block("Start", "green")
+    >>> block_1.id
+    '1'
+    >>> block_2 = Block("End", "red", parent=block_1)
+    >>> block_2.id
+    '2'
+    """
+
+    tikz_options: str = ", ".join(
+        [
+            "anchor=west",
+            "align=center",
+            "fill={fill_color}",
+            "draw=black",
+            "minimum height=1cm",
+            "rounded corners=0.3mm",
+            "inner sep=4pt",
+            "outer sep=0pt",
+        ]
+    )
+
+    def __init__(
+        self,
+        text: str,
+        color: str,
+        parent: Optional["Block"] = None,
+        shift: tuple[float, float] = (0.0, 0.0),
+    ) -> None:
+        self.text = text
+        self.color = color
+        self.parent = parent
+        self.shift = shift
+        self.id: str = str(int(self.parent.id) + 1) if self.parent is not None else "1"
+
+    @property
+    def position(self) -> str:
+        """Block position TikZ string."""
+
+        if self.parent is None:
+            return ""
+
+        return f"[right={0.5 + self.shift[0]}cm of {self.parent.id}, yshift={self.shift[1]}cm]"
+
+    def arrow(self, connector_position: float) -> str:
+        """Get TikZ arrow string.
+
+
+        Parameters
+        ----------
+        connector_position : float
+            distance in cm to right angle bend in connector
+
+        Returns
+        -------
+        str
+            TikZ string for arrow from `parent` to `self` or empty string if `parent` is `None`
+        """
+
+        if self.parent is None:
+            return ""
+
+        return "".join(
+            [
+                f"\\draw[thick, rectangle connector={connector_position}cm]",
+                f"({self.parent.id}.east) to ({self.id}.west);\n\n",
+            ]
+        )
+
+    def get_node(self, connector_position: float = 0.25) -> str:
+        """Get TikZ node string.
+
+        Parameters
+        ----------
+        connector_position : float, default: 0.25
+            distance in cm to right angle bend in connector
+
+        Returns
+        -------
+        str
+            TikZ string for rendering block
+        """
+
+        node = "".join(
+            [
+                "% Block\n",
+                f"\\node[{self.tikz_options.format(fill_color=self.color)}] ",
+                f"({self.id}) ",
+                self.position,
+                f"{{{self.text}}};\n",
+                self.arrow(connector_position),
+            ]
+        )
+        return node
+
+    def __add__(self, block: "Block") -> "Series":
+        """Add two `Block` instances to make a `Series` instance.
+
+        Parameters
+        ----------
+        block : Block
+            another `Block` instance
+
+        Returns
+        -------
+        Series
+            `Series` instance with `blocks = [self, block]`
+
+        Raises
+        ------
+        TypeError
+            If `block` is not an instance of `Block`
+        """
+
+        if not isinstance(block, Block):
+            raise TypeError(
+                f"cannot add object of type {type(block)=} to Block instance."
+            )
+
+        return Series([self, block], parent=self.parent)
+
+    def __mul__(self, value: int) -> "Group":
+        """Multiply `Block` instance by `value` to make `Group` with repeated blocks.
+
+        Parameters
+        ----------
+        value : int
+            multiplicative factor
+
+        Returns
+        -------
+        Group
+            `Group` instance with `value` copies of block
+
+        Raises
+        ------
+        ValueError
+            If `value` is not a positive integer
+        """
+
+        if not isinstance(value, int) or value <= 0:
+            raise ValueError("Multiplicative factor `value` must be a positive integer")
+
+        blocks: list[Block] = [deepcopy(self) for _ in range(value)]
+
+        return Group(blocks, parent=self.parent)
+
+    __rmul__ = __mul__
+
+
+class Series(Block):
+    """Series configuration of `Block` instances for horisontal grouping.
+
+    Parameters
+    ----------
+    blocks : list[Block]
+        list of `Block` instances
+    text: str, optional
+        series label text
+    color: str, optional
+        series color
+    parent : Optional[Block]
+        parent `Block` instance
+
+    Attributes
+    ----------
+    tikz_options : str
+        TikZ node options
+
+    """
+
+    tikz_options: str = ", ".join(
+        [
+            "anchor=west",
+            "align=center",
+            "inner sep=0pt",
+            "outer sep=0pt",
+        ]
+    )
+
+    def __init__(
+        self,
+        blocks: list[Block],
+        text: str = "",
+        color: str = "",
+        parent: Optional[Block] = None,
+    ) -> None:
+        Block.__init__(self, text, color, parent)
+
+        self.blocks = blocks
+        self.blocks[0].id = f"{self.id}+0"
+        for i, (block, new_parent) in enumerate(
+            zip(self.blocks[1::], self.blocks[0:-1]), start=1
+        ):
+            block.parent = new_parent
+            block.id = f"{self.id}+{i}"
+
+    @property
+    def background(self) -> str:
+        """Background rectangle TikZ string."""
+
+        if self.color in ("white", ""):
+            return ""
+
+        return "".join(
+            [
+                "\\begin{pgfonlayer}{background}\n",
+                f"\\coordinate (sw) at ($({self.id}.south west)+(-1mm, -1mm)$);\n",
+                f"\\coordinate (ne) at ($({self.id}.north east)+(1mm, 1mm)$);\n",
+                f"\\draw[{self.color}, thick] (sw) rectangle (ne);\n",
+                "\\end{pgfonlayer}\n",
+            ]
+        )
+
+    @property
+    def label(self) -> str:
+        """Series label string."""
+
+        if len(self.text) == 0:
+            return ""
+
+        return "".join(
+            [
+                f"\\coordinate (nw) at ($({self.id}.north west)+(-1mm, 1mm)$);\n",
+                f"\\coordinate (ne) at ($({self.id}.north east)+(1mm, 1mm)$);\n",
+                f"\\coordinate (n) at ($({self.id}.north)+(0mm, 1mm)$);\n",
+                f"\\draw[{self.color}, fill={self.color}!50, thick] (nw) ",
+                "rectangle ($(ne)+(0, 0.5cm)$);\n",
+                f"\\node[anchor=south] at (n) {{{self.text}}};\n",
+            ]
+        )
+
+    def get_node(self, connector_position: float = 0.25) -> str:
+        """Get TikZ node string.
+
+        Parameters
+        ----------
+        connector_position : float, default: 0.25
+            distance in cm to right angle bend in connector
+
+        Returns
+        -------
+        str
+            TikZ string for rendering series
+
+        """
+
+        block_nodes = "\n".join(
+            block.get_node(connector_position) for block in self.blocks
+        )
+        series_node = "".join(
+            [
+                f"\\node[{self.tikz_options}]",
+                f"({self.id})",
+                self.position,
+                "{\\begin{tikzpicture}\n",
+                block_nodes,
+                "\\end{tikzpicture}};\n\n",
+                self.arrow(connector_position),
+                self.background,
+                self.label,
+            ]
+        )
+        return series_node
+
+
+class Group(Block):
+    """Group of `Block` instances for vertical stacking.
+
+    Parameters
+    ----------
+    blocks : list[Block]
+        list of `Block` instances
+    text : str, optional
+        group label text
+    color : str, optional
+        group color
+    parent : Optional[Block]
+        parent `Block` instance
+
+    Attributes
+    ----------
+    shift_scale : float
+        scaling factor for vertical shifts of blocks
+    tikz_options : str
+        TikZ node options
+    """
+
+    shift_scale: float = 1.2
+    tikz_options: str = ", ".join(
+        [
+            "anchor=west",
+        ]
+    )
+
+    def __init__(
+        self,
+        blocks: list[Block],
+        text: str = "",
+        color: str = "",
+        parent: Optional[Block] = None,
+    ) -> None:
+        Block.__init__(self, text, color, parent)
+
+        self.blocks = blocks
+        for i, (block, shift) in enumerate(zip(self.blocks, self.shifts)):
+            block.shift = (0, shift)
+            block.parent = self
+            block.id = f"{self.id}-{i}"
+
+    @property
+    def shifts(self) -> list[float]:
+        """List of vertical position shifts for each `Block` instance in group.
+
+        Returns
+        -------
+        list[float]
+            list of vertical position shifts for each `Block` instance in group
+        """
+
+        n_blocks = len(self.blocks)
+
+        return list(-self.shift_scale * n for n in range(n_blocks))
+
+    @property
+    def background(self) -> str:
+        """Background rectangle TikZ string."""
+
+        if self.color in ("white", ""):
+            return ""
+
+        return "".join(
+            [
+                "\\begin{pgfonlayer}{background}\n",
+                f"\\coordinate (sw) at ($({self.id}.south west)+(-1mm, -1mm)$);\n",
+                f"\\coordinate (ne) at ($({self.id}.north east)+(1mm, 1mm)$);\n",
+                f"\\draw[{self.color}, thick] (sw) rectangle (ne);\n",
+                "\\end{pgfonlayer}\n",
+            ]
+        )
+
+    @property
+    def label(self) -> str:
+        """Series label string."""
+
+        if len(self.text) == 0:
+            return ""
+
+        return "".join(
+            [
+                f"\\coordinate (nw) at ($({self.id}.north west)+(-1mm, 1mm)$);\n",
+                f"\\coordinate (ne) at ($({self.id}.north east)+(1mm, 1mm)$);\n",
+                f"\\coordinate (n) at ($({self.id}.north)+(0mm, 1mm)$);\n",
+                f"\\draw[{self.color}, fill={self.color}!50, thick] (nw) ",
+                "rectangle ($(ne)+(0, 0.5cm)$);\n",
+                f"\\node[anchor=south] at (n) {{{self.text}}};\n",
+            ]
+        )
+
+    def arrow(self, connector_position: float) -> str:
+        """Get TikZ arrow string.
+
+        Parameters
+        ----------
+        connector_position : float
+            distance in cm to right angle bend in connector (not used in `Group` class)
+
+        Returns
+        -------
+        str
+            TikZ string for arrow from `parent` to `self` or empty string if `parent` is `None`
+        """
+
+        if self.parent is None:
+            return ""
+
+        return f"\\draw[thick] ({self.parent.id}.east) to ({self.id}.west);\n"
+
+    @property
+    def arrows(self) -> str:
+        """Get TikZ string for arrow connecting stacked blocks."""
+
+        return "\n".join(
+            [
+                " ".join(
+                    [
+                        "\\draw[thick, rectangle line]",
+                        f"({block1.id}.east) to ({block2.id}.east);\n",
+                    ]
+                )
+                for (block1, block2) in combinations(self.blocks, 2)
+            ]
+        )
+
+    def get_node(self, connector_position: float = 0.0) -> str:
+        """Get TikZ node string.
+
+        Parameters
+        ----------
+        connector_position : float, default: 0.0
+            distance in cm to right angle bend in connector
+
+        Returns
+        -------
+        str
+            TikZ string for rendering group
+        """
+
+        block_nodes = "\n".join(
+            block.get_node(connector_position) for block in self.blocks
+        )
+
+        group_node = "".join(
+            [
+                f"\\node[anchor=west, outer sep=0pt, inner sep=0pt, align=center] ({self.id}) ",
+                self.position,
+                "{\\begin{tikzpicture}\n",
+                f"\\coordinate ({self.id}) at (0, 0);\n",
+                block_nodes,
+                self.arrows,
+                "\\end{tikzpicture}};\n\n",
+                self.arrow(connector_position),
+                self.background,
+                self.label,
+            ]
+        )
+
+        return group_node

pyrbd/diagram.py

@@ -0,0 +1,186 @@
+"""Module containing Diagram class definition."""
+
+import subprocess
+
+import pymupdf
+
+from .block import Block
+
+
+class Diagram:
+    """Reliability block diagram class definition.
+
+    Parameters
+    ----------
+    name : str
+        name of diagram
+    blocks : list[Block]
+        list of `Block` instances
+    hazard : str, optional
+        string defining the `hazard` block text
+    """
+
+    def __init__(self, name: str, blocks: list[Block], hazard: str = "") -> None:
+        self.filename = name
+        if hazard:
+            self.head = Block(hazard, "red!60")
+        else:
+            self.head = blocks.pop(0)
+
+        self.head.id = "0"
+        self.blocks = blocks
+        self.blocks[0].parent = self.head
+
+    def write(self) -> None:
+        """Write diagram to .tex file."""
+
+        with open(f"{self.filename}.tex", mode="w", encoding="utf-8") as file:
+            file.write(TEX_PREAMBLE)
+            for block in [self.head, *self.blocks]:
+                file.write(block.get_node())
+            file.write(TEX_END)
+
+    def _to_svg(self) -> str:
+        """Convert diagram file from pdf to svg.
+
+        Returns
+        -------
+        str
+            filename of .svg file
+        """
+
+        pdf_document = pymupdf.open(f"{self.filename}.pdf")
+        page = pdf_document[0]
+
+        # Get and convert page to svg image
+        svg_content = page.get_svg_image()
+
+        # Save to file
+        with open(output_file := f"{self.filename}.svg", "w", encoding="utf-8") as file:
+            file.write(svg_content)
+
+        pdf_document.close()
+
+        return output_file
+
+    def _to_png(self) -> str:
+        """Convert diagram file from pdf to png.
+
+        Returns
+        -------
+        str
+            filename of .png file
+        """
+
+        pdf_document = pymupdf.open(f"{self.filename}.pdf")
+        page = pdf_document[0]
+
+        # Get image
+        image = page.get_pixmap(dpi=300)  # type: ignore
+
+        # Save to file
+        image.save(output_file := f"{self.filename}.png")
+
+        pdf_document.close()
+
+        return output_file
+
+    def compile(
+        self, output: str | list[str] = "pdf", clear_source: bool = True
+    ) -> list[str]:
+        """Compile diagram .tex file.
+
+        Parameters
+        ----------
+        output : str | list[str], default: 'pdf'
+            output format string or list of output formats for diagram. Valid output formats are
+
+            - `'pdf'` (default)
+            - `'svg'`
+            - `'png'`
+
+        clear_source : bool, default: True
+            .tex source file is deleted after compilation if `True`
+
+        Returns
+        -------
+        list[str]
+            list of output filenames
+
+        Raises
+        ------
+        FileNotFoundError
+            If .tex file is not found, e.g. because `Diagram.write()` has not been called
+            before `Diagram.compile()`.
+        """
+
+        try:
+            subprocess.check_call(["latexmk", f"{self.filename}.tex", "--silent"])
+            subprocess.check_call(["latexmk", "-c", f"{self.filename}.tex"])
+            if clear_source:
+                subprocess.check_call(["rm", f"{self.filename}.tex"])
+        except subprocess.CalledProcessError as err:
+            if err.returncode == 11:
+                raise FileNotFoundError(
+                    (
+                        f"File {self.filename} not found. "
+                        + "Check if call to Class method write() is missing."
+                    )
+                ) from err
+
+        output_files: list[str] = []
+
+        if not isinstance(output, list):
+            output = [output]
+
+        if "svg" in output:
+            output_files.append(self._to_svg())
+        if "png" in output:
+            output_files.append(self._to_png())
+        if "pdf" not in output:
+            subprocess.check_call(["rm", f"{self.filename}.pdf"])
+        else:
+            output_files.append(f"{self.filename}.pdf")
+
+        return output_files
+
+
+TEX_PREAMBLE = "\n".join(
+    [
+        r"\documentclass{standalone}",
+        r"\usepackage{tikz}",
+        r"\usetikzlibrary{shapes,arrows,positioning,calc}",
+        r"\pgfdeclarelayer{background}",
+        r"\pgfsetlayers{background, main}",
+        r"\tikzset{",
+        r"connector/.style={",
+        r"-latex,",
+        r"font=\scriptsize},",
+        r"line/.style={",
+        r"font=\scriptsize},",
+        r"rectangle connector/.style={",
+        r"connector,"
+        r"to path={(\tikztostart) -- ++(#1,0pt) \tikztonodes |- (\tikztotarget) },",
+        r"pos=0.5},"
+        r"rectangle connector/.default=0.5cm,",
+        r"rectangle line/.style={",
+        r"line,"
+        r"to path={(\tikztostart) -- ++(#1,0pt) \tikztonodes |- (\tikztotarget) },",
+        r"pos=0.5},"
+        r"rectangle line/.default=0.5cm,",
+        r"straight connector/.style={",
+        r"connector,",
+        r"to path=--(\tikztotarget) \tikztonodes}",
+        r"}",
+        r"\begin{document}",
+        r"\begin{tikzpicture}",
+        "",
+    ]
+)
+
+TEX_END = "\n".join(
+    [
+        r"\end{tikzpicture}",
+        r"\end{document}",
+    ]
+)

pyrbd-0.2.5.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: pyrbd
+Version: 0.2.5
+Summary: Package for creating simple reliability block diagrams (RBDs) using LaTeX and TikZ.
+Project-URL: Repository, https://github.com/hghugdal/pyrbd
+Project-URL: Issues, https://github.com/hghugdal/pyrbd/issues
+Project-URL: Documentation, https://hghugdal.github.io/pyrbd
+Author-email: hghugdal <hghugdal@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pymupdf>=1.26.3
+Description-Content-Type: text/markdown
+
+# <img alt="pyRBDlogo" src=docs/images/logo.svg width=40 align=top> pyRBD
+
+<img alt="Python" src="https://img.shields.io/badge/Python->= 3.10-blue?logo=python&link=None"> ![PyPI - Version](https://img.shields.io/pypi/v/pyrbd?link=https%3A%2F%2Fpypi.org%2Fproject%2Fpyrbd) <img alt="Tests" src="https://img.shields.io/badge/Tests-Passing-darkgreen?logo=pytest&link=None"> <img alt="Coverage" src="https://img.shields.io/badge/Coverage-100%25-darkgreen?link=None"> <img alt="Pylint" src="https://img.shields.io/badge/Pylint-10%2F10-darkgreen?link=None">
+
+A Python package for creating simple reliability block diagrams (RBDs) using `LaTeX` and [`TikZ`](https://en.wikipedia.org/wiki/PGF/TikZ).
+
+## Dependencies
+`pyRBD` requires a working installation of `LaTeX` including [`TikZ`](https://en.wikipedia.org/wiki/PGF/TikZ) and [`latexmk`](https://ctan.org/pkg/latexmk/).
+
+## Simple example diagram
+The blocks of the RBD are defined using `Block`, `Series` and `Group`, and the diagram itself is handled by the `Diagram` class. A simple example is given by the code
+```python linenums="1"
+from pyrbd import Block, Diagram
+
+start_block = Block("Start", "blue!30", parent=None)
+parallel = 2 * Block("Parallel blocks", "gray", parent=start_block)
+end_block = Block("End", "green!50", parent=parallel)
+
+diagram = Diagram(
+    "simple_RBD",
+    blocks=[start_block, parallel, end_block],
+)
+diagram.write()
+diagram.compile()
+```
+producing the following diagram
+<div><img src="docs/examples/simple_RBD.svg" width=500/></div>
+
+For more examples, visit the [documentation](https://hghugdal.github.io/pyrbd/).

pyrbd-0.2.5.dist-info/RECORD

@@ -0,0 +1,7 @@
+pyrbd/__init__.py,sha256=mpsb022BX9eDGSBhuYIr2gOr4sg_M9sYbPGHLPIdvl0,219
+pyrbd/block.py,sha256=ETRZJeEUU4OPk0qGo6zZIsaR1oLkyDPf1kelfuKWNsc,12219
+pyrbd/diagram.py,sha256=NVAsdfmqAu6-6J2mT5Gp2W_8a9WsI2iMbKjcEI6QFlE,5092
+pyrbd-0.2.5.dist-info/METADATA,sha256=WN1raYOu5KJtH5wj-7b1P8wH8-1GGHmnnqvwrt5hmZs,2196
+pyrbd-0.2.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pyrbd-0.2.5.dist-info/licenses/LICENSE,sha256=mxXMgWpFgk71JpEEElFrb9FJxeoaDgvrU8gjUUU9LzA,1069
+pyrbd-0.2.5.dist-info/RECORD,,

pyrbd-0.2.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyrbd-0.2.5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 H. G. Hugdal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.