qmm-core 0.2.2__tar.gz

qmm_core-0.2.2/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Jayden Hyman
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

qmm_core-0.2.2/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.1
+Name: qmm-core
+Version: 0.2.2
+Summary: A software platform for analysing the structure and function of complex systems
+Author-email: Jayden Hyman <j.hyman@uq.edu.au>
+Project-URL: Homepage, https://github.com/jaydenhyman/qmm
+Project-URL: Bug Tracker, https://github.com/jaydenhyman/qmm/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest
+Requires-Dist: numpy
+Requires-Dist: sympy
+Requires-Dist: networkx
+Requires-Dist: graphviz
+Requires-Dist: numba
+Requires-Dist: pandas
+Requires-Dist: seaborn
+Requires-Dist: matplotlib
+
+# ![QMM Logo](https://github.com/jaydenhyman/qmm/blob/6f9beb2d90807e8fbc9622a4db3cdf7c0fcd06aa/logo.png) QMM: Qualitative Mathematical Modelling
+
+QMM is a software platform for analysing the structure and function of complex systems.
+
+## Features
+
+- Interactive web application for creating signed digraph (network) models representing the mathematical structure of a complex system.
+- Python package (`qmm`) for qualitative mathematical modelling, including core modules for defining model structure, stability analysis, press perturbation analysis and making qualitative predictions.
+
+## Contact
+
+For any additional information or questions, please contact:
+
+Jayden Hyman: <j.hyman@uq.edu.au>
+
+## How to use
+
+1. Install Python and required packages:
+
+   Option 1: Using Anaconda and JupyterLab (Recommended)
+
+   a. Install Anaconda from <https://www.anaconda.com/products/distribution>
+
+   b. Launch Anaconda Navigator
+
+   c. Create a new environment:
+      - Click on "Environments" in the left sidebar
+      - Click "Create" at the bottom
+      - Name your environment (e.g., "qmm") and select Python 3.10
+      - Click "Create"
+      - In the "Environments" list, click on your newly created environment
+
+   d. Install JupyterLab:
+      - With your new environment selected, go to the "Home" tab
+      - Find JupyterLab in the list of applications
+      - Click "Install"
+
+   This method uses Anaconda's default packages, which include NumPy, SymPy, NetworkX, Pandas, Numba, and Graphviz. JupyterLab provides an integrated development environment for running QMM package functions.
+
+   Option 2: Using Miniconda
+
+   a. Install Miniconda from <https://docs.conda.io/en/latest/miniconda.html>
+
+   b. Open a Miniconda prompt and create a new environment:
+
+      ```bash
+      conda create -n qmm python=3.10
+      conda activate qmm
+      ```
+
+   c. Install the required packages:
+
+      ```bash
+      conda install numpy=1.26.4 networkx=3.3 pandas=2.0.2 numba=0.60.0 sympy=1.13
+      conda install -c conda-forge graphviz=0.20.3
+      ```
+
+2. Use the web application to create signed digraph models: [Open in browser](https://d2x70551if0frn.cloudfront.net/)
+
+3. The `qmm.ipynb` file provides core functions to analyse signed digraph models. To get started with analysing your model, open this file in JupyterLab or your preferred Python IDE.
+
+## Documentation
+
+Detailed documentation for the `qmm` package and its modules is not currently available.
+
+## Licensing
+
+This model is licensed under a BSD 3-Clause License. See LICENSE.md for further information.
+
+## Attribution
+
+A Zenodo will be available in the near future for attribution.
+
+## Contributing
+
+We welcome contributions to improve and expand the QMM software. As the project is in its early stages of development, we appreciate your patience and support in helping us refine the software.

qmm_core-0.2.2/README.md

@@ -0,0 +1,76 @@
+# ![QMM Logo](https://github.com/jaydenhyman/qmm/blob/6f9beb2d90807e8fbc9622a4db3cdf7c0fcd06aa/logo.png) QMM: Qualitative Mathematical Modelling
+
+QMM is a software platform for analysing the structure and function of complex systems.
+
+## Features
+
+- Interactive web application for creating signed digraph (network) models representing the mathematical structure of a complex system.
+- Python package (`qmm`) for qualitative mathematical modelling, including core modules for defining model structure, stability analysis, press perturbation analysis and making qualitative predictions.
+
+## Contact
+
+For any additional information or questions, please contact:
+
+Jayden Hyman: <j.hyman@uq.edu.au>
+
+## How to use
+
+1. Install Python and required packages:
+
+   Option 1: Using Anaconda and JupyterLab (Recommended)
+
+   a. Install Anaconda from <https://www.anaconda.com/products/distribution>
+
+   b. Launch Anaconda Navigator
+
+   c. Create a new environment:
+      - Click on "Environments" in the left sidebar
+      - Click "Create" at the bottom
+      - Name your environment (e.g., "qmm") and select Python 3.10
+      - Click "Create"
+      - In the "Environments" list, click on your newly created environment
+
+   d. Install JupyterLab:
+      - With your new environment selected, go to the "Home" tab
+      - Find JupyterLab in the list of applications
+      - Click "Install"
+
+   This method uses Anaconda's default packages, which include NumPy, SymPy, NetworkX, Pandas, Numba, and Graphviz. JupyterLab provides an integrated development environment for running QMM package functions.
+
+   Option 2: Using Miniconda
+
+   a. Install Miniconda from <https://docs.conda.io/en/latest/miniconda.html>
+
+   b. Open a Miniconda prompt and create a new environment:
+
+      ```bash
+      conda create -n qmm python=3.10
+      conda activate qmm
+      ```
+
+   c. Install the required packages:
+
+      ```bash
+      conda install numpy=1.26.4 networkx=3.3 pandas=2.0.2 numba=0.60.0 sympy=1.13
+      conda install -c conda-forge graphviz=0.20.3
+      ```
+
+2. Use the web application to create signed digraph models: [Open in browser](https://d2x70551if0frn.cloudfront.net/)
+
+3. The `qmm.ipynb` file provides core functions to analyse signed digraph models. To get started with analysing your model, open this file in JupyterLab or your preferred Python IDE.
+
+## Documentation
+
+Detailed documentation for the `qmm` package and its modules is not currently available.
+
+## Licensing
+
+This model is licensed under a BSD 3-Clause License. See LICENSE.md for further information.
+
+## Attribution
+
+A Zenodo will be available in the near future for attribution.
+
+## Contributing
+
+We welcome contributions to improve and expand the QMM software. As the project is in its early stages of development, we appreciate your patience and support in helping us refine the software.

qmm_core-0.2.2/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qmm-core"
+version = "0.2.2"
+authors = [
+  { name="Jayden Hyman", email="j.hyman@uq.edu.au" },
+]
+description = "A software platform for analysing the structure and function of complex systems"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3.10",
+]
+dependencies = [
+    "pytest",
+    "numpy",
+    "sympy",
+    "networkx",
+    "graphviz",
+    "numba",
+    "pandas",
+    "seaborn",
+    "matplotlib",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/jaydenhyman/qmm"
+"Bug Tracker" = "https://github.com/jaydenhyman/qmm/issues"
+
+[tool.setuptools.packages.find]
+exclude = ["tests*"]
+
+[tool.setuptools.package-data]
+qmm = ["py.typed"]

qmm_core-0.2.2/qmm/__init__.py

@@ -0,0 +1,90 @@
+from .core.structure import (
+    import_digraph,
+    create_matrix,
+    create_equations,
+)
+
+from .core.stability import (
+    sign_stability,
+    system_feedback,
+    net_feedback,
+    absolute_feedback,
+    weighted_feedback,
+    feedback_metrics,
+    hurwitz_determinants,
+    net_determinants,
+    absolute_determinants,
+    weighted_determinants,
+    determinants_metrics,
+    conditional_stability,
+    simulation_stability,
+)
+
+from .core.press import (
+    adjoint_matrix,
+    absolute_feedback_matrix,
+    weighted_predictions_matrix,
+    sign_determinacy_matrix,
+    numerical_simulations,
+)
+
+from .core.prediction import (
+    table_of_predictions,
+    compare_predictions,
+    create_plot,
+)
+
+from .core.helper import (
+    list_to_digraph,
+    digraph_to_list,
+    powerplay_labels,
+    perm,
+    get_nodes,
+    get_positive,
+    get_negative,
+    get_weight,
+    sign_determinacy,
+    display_digraph,
+)
+
+__all__ = [
+    # structure.py
+    "import_digraph",
+    "display_digraph",
+    "create_matrix",
+    "create_equations",
+    # stability.py
+    "sign_stability",
+    "system_feedback",
+    "net_feedback",
+    "absolute_feedback",
+    "weighted_feedback",
+    "feedback_metrics",
+    "hurwitz_determinants",
+    "net_determinants",
+    "absolute_determinants",
+    "weighted_determinants",
+    "determinants_metrics",
+    "conditional_stability",
+    "simulation_stability",
+    # press.py
+    "adjoint_matrix",
+    "absolute_feedback_matrix",
+    "weighted_predictions_matrix",
+    "sign_determinacy_matrix",
+    "numerical_simulations",
+    # prediction.py
+    "table_of_predictions",
+    "compare_predictions",
+    "create_plot",
+    # helper.py
+    "list_to_digraph",
+    "digraph_to_list",
+    "powerplay_labels",
+    "perm",
+    "get_nodes",
+    "get_positive",
+    "get_negative",
+    "get_weight",
+    "sign_determinacy",
+]

qmm_core-0.2.2/qmm/core/helper.py

@@ -0,0 +1,324 @@
+import numpy as np
+import sympy as sp
+import networkx as nx
+from numba import jit
+import graphviz
+
+def list_to_digraph(matrix, ids=None):
+    if not isinstance(matrix, (list, np.ndarray)):
+        raise ValueError("Input must be a list of lists or a numpy array")
+    if isinstance(matrix, list):
+        matrix = np.array(matrix)
+    if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
+        raise ValueError("Input must be a square matrix")
+    G = nx.DiGraph()
+    n = matrix.shape[0]
+    if ids is None:
+        node_ids = [str(i) for i in range(1, n + 1)]
+    else:
+        if len(ids) != n:
+            raise ValueError("Number of ids must match matrix dimensions")
+        node_ids = ids
+    G.add_nodes_from(node_ids)
+    for i in range(n):
+        for j in range(n):
+            if matrix[i][j] != 0:
+                G.add_edge(node_ids[j], node_ids[i], sign=int(matrix[i][j]))
+    nx.set_node_attributes(G, "state", "category")
+    return G
+
+
+def digraph_to_list(G):
+    if not isinstance(G, nx.DiGraph):
+        raise TypeError("Input must be a networkx.DiGraph.")
+    n = G.number_of_nodes()
+    nodes = sorted(G.nodes())
+    node_to_index = {node: i for i, node in enumerate(nodes)}
+    matrix = [[0 for _ in range(n)] for _ in range(n)]
+    for source, target, data in G.edges(data=True):
+        i, j = node_to_index[source], node_to_index[target]
+        sign = data.get("sign", 1)
+        matrix[j][i] = sign
+    return str(matrix)
+
+
+def powerplay_labels(input_str):
+    return [item.split(": ")[1] for item in input_str.split(", ")]
+
+
+def perm(A, method="glynn"):
+    if not isinstance(A, np.ndarray):
+        raise TypeError("Input matrix must be a NumPy array.")
+    matshape = A.shape
+    if matshape[0] != matshape[1]:
+        raise ValueError("Input matrix must be square.")
+    if np.isnan(A).any():
+        raise ValueError("Input matrix must not contain NaNs.")
+    if matshape[0] == 0:
+        return A.dtype.type(1.0)
+    if matshape[0] == 1:
+        return A[0, 0]
+    if matshape[0] == 2:
+        return A[0, 0] * A[1, 1] + A[0, 1] * A[1, 0]
+    if matshape[0] == 3:
+        return (
+            A[0, 2] * A[1, 1] * A[2, 0]
+            + A[0, 1] * A[1, 2] * A[2, 0]
+            + A[0, 2] * A[1, 0] * A[2, 1]
+            + A[0, 0] * A[1, 2] * A[2, 1]
+            + A[0, 1] * A[1, 0] * A[2, 2]
+            + A[0, 0] * A[1, 1] * A[2, 2]
+        )
+    return _ryser(A) if method != "glynn" else _glynn(A)
+
+
+@jit(nopython=True)
+def _ryser(A):
+    n = len(A)
+    if n == 0:
+        return A.dtype.type(1.0)
+    row_comb = np.zeros((n), dtype=A.dtype)
+    total = 0
+    old_grey = 0
+    sign = +1
+    binary_power_dict = [2**i for i in range(n)]
+    num_loops = 2**n
+    for k in range(0, num_loops):
+        bin_index = (k + 1) % num_loops
+        reduced = np.prod(row_comb)
+        total += sign * reduced
+        new_grey = bin_index ^ (bin_index // 2)
+        grey_diff = old_grey ^ new_grey
+        grey_diff_index = binary_power_dict.index(grey_diff)
+        new_vector = A[grey_diff_index]
+        direction = (old_grey > new_grey) - (old_grey < new_grey)
+        for i in range(n):
+            row_comb[i] += new_vector[i] * direction
+        sign = -sign
+        old_grey = new_grey
+    return total
+
+
+@jit(nopython=True)
+def _glynn(A):
+    n = len(A)
+    if n == 0:
+        return A.dtype.type(1.0)
+    row_comb = np.sum(A, 0)
+    total = 0
+    old_gray = 0
+    sign = +1
+    binary_power_dict = [2**i for i in range(n)]
+    num_loops = 2 ** (n - 1)
+    for bin_index in range(1, num_loops + 1):
+        reduced = np.prod(row_comb)
+        total += sign * reduced
+        new_gray = bin_index ^ (bin_index // 2)
+        gray_diff = old_gray ^ new_gray
+        gray_diff_index = binary_power_dict.index(gray_diff)
+        new_vector = A[gray_diff_index]
+        direction = 2 * ((old_gray > new_gray) - (old_gray < new_gray))
+        for i in range(n):
+            row_comb[i] += new_vector[i] * direction
+        sign = -sign
+        old_gray = new_gray
+    return total / num_loops
+
+
+def get_nodes(G, node_type="state", labels=False):
+    if not isinstance(G, nx.DiGraph):
+        raise TypeError("Input must be a networkx.DiGraph.")
+
+    if node_type == "all":
+        return list(G.nodes()) if not labels else list(G.nodes(data=True))
+    else:
+        return [
+            n if not labels else d.get("label", n)
+            for n, d in G.nodes(data=True)
+            if d.get("category") == node_type
+        ]
+
+
+def get_weight(net, absolute, no_effect=sp.nan):
+    if net.shape != absolute.shape:
+        raise ValueError("Matrices must have the same shape")
+    result = sp.zeros(*net.shape)
+    for i in range(net.shape[0]):
+        for j in range(net.shape[1]):
+            if absolute[i, j] == 0:
+                result[i, j] = no_effect
+            else:
+                result[i, j] = net[i, j] / absolute[i, j]
+    return result
+
+
+def get_positive(net, absolute):
+    if net.shape != absolute.shape:
+        raise ValueError("Matrices must have the same shape")
+    result = sp.zeros(*net.shape)
+    for i in range(net.shape[0]):
+        for j in range(net.shape[1]):
+            result[i, j] = (net[i, j] + absolute[i, j]) // 2
+    return result
+
+
+def get_negative(net, absolute):
+    if net.shape != absolute.shape:
+        raise ValueError("Matrices must have the same shape")
+    result = sp.zeros(*net.shape)
+    for i in range(net.shape[0]):
+        for j in range(net.shape[1]):
+            result[i, j] = (absolute[i, j] - net[i, j]) // 2
+    return result
+
+
+def sign_determinacy(wmat, tmat, method="average"):
+    def compute_prob(w, t, method):
+        if w == sp.Integer(0):
+            return sp.Rational(1, 2)
+        elif w == sp.Integer(1):
+            return sp.Integer(1)
+        elif w == sp.Integer(-1):
+            return sp.Integer(-1)
+        elif t == sp.Integer(0):
+            return sp.nan
+        return (
+            compute_prob_average(w, t)
+            if method == "average"
+            else compute_prob_95_bound(w, t)
+        )
+
+    def compute_prob_average(w, t):
+        bw = 3.45962
+        bwt = 0.03417
+        prob = sp.exp(bw * w + bwt * w * t) / (1 + sp.exp(bw * w + bwt * w * t))
+        return max(sp.Rational(1, 2), prob)
+
+    def compute_prob_95_bound(w, t):
+        bw = 9.766
+        bwt = 0.139
+        prob = sp.exp(bw * w + bwt * w * t) / (1253.992 + sp.exp(bw * w + bwt * w * t))
+        return max(sp.Rational(1, 2), prob)
+
+    if method not in ["average", "95_bound"]:
+        raise ValueError("Invalid method. Choose 'average' or '95_bound'.")
+
+    rows, cols = wmat.shape
+
+    def calc_prob(i, j):
+        w, t = wmat[i, j], tmat[i, j]
+        if w.is_zero:
+            return sp.Rational(1, 2)
+        prob = compute_prob(sp.Abs(w), t, method)
+        return sp.sign(w) * prob if prob is not None else sp.nan
+
+    pmat = sp.Matrix(rows, cols, lambda i, j: calc_prob(i, j))
+    return pmat
+
+
+def arrows(G, path):
+    arrows = []
+    for i in range(len(path) - 1):
+        if G[path[i]][path[i + 1]]["sign"] > 0:
+            arrows.append(f"{path[i]} $\\rightarrow$")  # Right arrow
+        else:
+            arrows.append(f"{path[i]} $\\multimap$")  # Multimap
+    arrows.append(str(path[-1]))
+    return " ".join(arrows)
+
+
+def sign_string(G, path):
+    signs = []
+    for from_node, to_node in zip(path, path[1:]):
+        sign = G[from_node][to_node]["sign"]
+        if sign != 0:
+            signs.append(int(sign))
+    product = sp.prod(signs)
+    if product > 0:
+        return "+"
+    elif product < 0:
+        return "\u2212"
+    else:
+        return "0"
+
+
+def symbolic_path(G, A, path, nodes):
+    if len(path) == 1:
+        return str(A[nodes.index(path[0]), nodes.index(path[0])])
+    return " * ".join(
+        str(A[nodes.index(path[i]), nodes.index(path[i + 1])])
+        for i in range(len(path) - 1)
+    )
+
+
+
+def display_digraph(G, label=False, output_format="svg", self_effects=True):
+    def set_lbl(node, idx):
+        return G.nodes[node].get("label", str(idx + 1)) if label else node
+
+    def dot_node(node, idx):
+        lbl = set_lbl(node, idx)
+        x = G.nodes[node].get("x", None)
+        y = G.nodes[node].get("y", None)
+        pos = f"{x / 100},{-y / 100}!" if x is not None and y is not None else ""
+        category = G.nodes[node].get("category")
+        if category == "input":
+            shape = "rectangle"
+            size = "0.45,0.45"
+            color = "#FFD0C9"  # Light red for input nodes
+        elif category == "output":
+            shape = "diamond"
+            size = "0.6,0.6"
+            color = "lightblue"  # Light blue for output nodes
+        elif category == "state":
+            shape = "oval"
+            size = "0.52,0.52"
+            color = "cornsilk"  # Light yellow for state nodes
+        else:
+            shape = "oval"
+            size = "0.52,0.52"
+            color = "whitesmoke"  # Default color
+        wrap = "\\n" if label else ""
+        fixsz = "false" if label else "true"
+        return (
+            f'    {node} [label="{lbl}{wrap}", pos="{pos}", '
+            f'shape={shape}, width={size.split(",")[0]}, '
+            f'height={size.split(",")[1]}, fixedsize={fixsz}, '
+            f'color="black", style="filled", fillcolor="{color}"];'
+        )
+
+    def dot_edge(src, tgt, sign):
+        arrow = "normal" if sign.get("sign", 1) == 1 else "dot"
+        return f"    {src} -> {tgt} [arrowhead={arrow}];"
+
+    has_positions = any(
+        "x" in G.nodes[node] and "y" in G.nodes[node] for node in G.nodes
+    )
+
+    dot = [
+        "digraph G {",
+        'layout = "neato";',
+    ]
+
+    if not has_positions:
+        dot.extend(
+            [
+                'graph [overlap=false, splines=true, sep="+10"];',
+                "node [fixedsize=true];",
+            ]
+        )
+
+    dot.extend(
+        [
+            "edge [labelangle=45, labeldistance=2.0];",
+            'edge [layer="back"];',
+            'node [layer="front"];',
+        ]
+    )
+
+    dot.extend(
+        dot_edge(s, t, d) for s, t, d in G.edges(data=True) if self_effects or s != t
+    )
+    dot.extend(dot_node(n, i) for i, n in enumerate(G.nodes))
+    dot.append("}")
+    return graphviz.Source("\n".join(dot), format=output_format)