qmm-core 0.2.2__py3-none-any.whl

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/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)

qmm/core/prediction.py

@@ -0,0 +1,74 @@
+import numpy as np
+import sympy as sp
+import pandas as pd
+import seaborn as sns
+import matplotlib.pyplot as plt
+
+
+def table_of_predictions(M, t1=0.8, t2=1, index=None, columns=None):
+    if isinstance(M, sp.Matrix):
+        M = sp.matrix2numpy(M, dtype=float)
+    conditions = [
+        (lambda x: x == sp.nan, "0"),
+        (lambda x: x >= t2, "+"),
+        (lambda x: x >= t1 and x < t2, "(+)"),
+        (lambda x: x > -t1 and x < t1, "?"),
+        (lambda x: x > -t2 and x <= -t1, "(\u2212)"),
+        (lambda x: x <= -t2, "\u2212"),
+    ]
+
+    predictions = np.empty(M.shape, dtype=object)
+    for i in range(M.shape[0]):
+        for j in range(M.shape[1]):
+            value = M[i, j]
+            predictions[i, j] = next(
+                (val for cond, val in conditions if cond(value)), "0"
+            )
+    return pd.DataFrame(predictions, index=index, columns=columns)
+
+
+def compare_predictions(M1, M2):
+    if not M1.index.equals(M2.index) or not M1.columns.equals(M2.columns):
+        raise ValueError("M1 and M2 must have the same index and columns")
+    combined = np.vectorize(lambda x, y: x if x == y else f"{x}, {y}")(
+        M1.values, M2.values
+    )
+    return pd.DataFrame(combined, index=M1.index, columns=M1.columns)
+
+
+def create_plot(data, **kwargs):
+    plt.rcParams.update(
+        {
+            "xtick.top": True,
+            "xtick.bottom": False,
+            "xtick.labeltop": True,
+            "xtick.labelbottom": False,
+            "xtick.major.width": 0.5,
+            "ytick.major.width": 0.5,
+            "xtick.major.size": 3,
+            "ytick.major.size": 3,
+            "xtick.minor.size": 1.5,
+            "ytick.minor.size": 1.5,
+        }
+    )
+    args = {
+        "annot": True,
+        "linewidths": 0.75,
+        "linecolor": "white",
+        "cbar": False,
+        "cmap": None,
+    }
+    args.update(kwargs)
+    figsize = args.pop("figsize", None)
+    if figsize:
+        fig, ax = plt.subplots(figsize=figsize)
+    else:
+        fig, ax = plt.subplots()
+    sns.heatmap(data, ax=ax, **args)
+    plt.setp(ax.get_xticklabels(), rotation=0, ha="center")
+    plt.setp(ax.get_yticklabels(), rotation=0, ha="right")
+    for spine in ax.spines.values():
+        spine.set_visible(True)
+        spine.set_color("white")
+        spine.set_linewidth(0.5)
+    return fig, ax

qmm/core/press.py

@@ -0,0 +1,119 @@
+import numpy as np
+import sympy as sp
+from functools import cache
+from .structure import create_matrix
+from .helper import perm, get_weight, get_nodes, sign_determinacy
+
+
+@cache
+def adjoint_matrix(G, form="symbolic", perturb=None):
+    A = create_matrix(G, form=form)
+    A = sp.Matrix(-A)
+    nodes = get_nodes(G, "state")
+    n = len(nodes)
+    if perturb is not None:
+        src_id = nodes.index(perturb)
+        return sp.Matrix(
+            [sp.Integer(-1) ** (src_id + j) * A.minor(src_id, j) 
+             for j in range(n)]
+        )
+    adjoint_matrix = sp.expand(A.adjugate())
+    return sp.Matrix(adjoint_matrix)
+
+
+@cache
+def absolute_feedback_matrix(G, perturb=None):
+    A = create_matrix(G, form="binary")
+    A_np = np.array(sp.matrix2numpy(A), dtype=int)
+    nodes = get_nodes(G, "state")
+    n = A_np.shape[0]
+    if perturb is not None:
+        perturb_index = nodes.index(perturb)
+        result = np.zeros(n, dtype=int)
+        for j in range(n):
+            minor = np.delete(np.delete(A_np, perturb_index, 0), j, 1)
+            result[j] = int(perm(minor.astype(float)))
+        return sp.Matrix(result)
+    tmat = np.zeros((n, n), dtype=int)
+    for i in range(n):
+        for j in range(n):
+            minor = np.delete(np.delete(A_np, j, 0), i, 1)
+            tmat[i, j] = int(perm(minor.astype(float)))
+    return sp.Matrix(tmat)
+
+
+@cache
+def weighted_predictions_matrix(G, perturb=None, as_nan=True, as_abs=False):
+    amat = adjoint_matrix(G, perturb=perturb, form="signed")
+    if as_abs:
+        amat = sp.Abs(amat)
+    tmat = absolute_feedback_matrix(G, perturb=perturb)
+    if as_nan:
+        wmat = get_weight(amat, tmat)
+    else:
+        wmat = get_weight(amat, tmat, sp.Integer(1))
+    return sp.Matrix(wmat)
+
+
+@cache
+def sign_determinacy_matrix(
+    G, perturb=None, method="average", as_nan=True, as_abs=False
+):
+    wmat = weighted_predictions_matrix(
+        G, perturb=perturb, as_nan=as_nan, as_abs=as_abs
+        )
+    tmat = sp.Matrix(absolute_feedback_matrix(G, perturb=perturb))
+    pmat = sign_determinacy(wmat, tmat, method)
+    return sp.Matrix(pmat)
+
+
+@cache
+def numerical_simulations(G, perturb=None, n_sim=10000, dist="uniform", seed=42, as_abs=False):
+    np.random.seed(seed)
+    A = create_matrix(G, form="symbolic", matrix_type="A")
+    state_nodes = get_nodes(G, "state")
+    node_idx = {node: i for i, node in enumerate(state_nodes)}
+    n = len(state_nodes)
+    symbols = list(A.free_symbols)
+    A_sp = sp.lambdify(symbols, A)
+    pert_idx, sign = (
+        (node_idx[perturb[0]], perturb[1]) 
+        if perturb else (None, 1)
+    )
+    dist_funcs = {
+        "uniform": lambda size: np.random.uniform(0, 1, size),
+        "weak": lambda size: np.random.beta(1, 3, size),
+        "moderate": lambda size: np.random.beta(2, 2, size),
+        "strong": lambda size: np.random.beta(3, 1, size),
+    }
+    positive = np.zeros((n, n), dtype=int)
+    negative = np.zeros((n, n), dtype=int)
+    total_simulations = 0
+    while total_simulations < n_sim:
+        values = dist_funcs[dist](len(symbols))
+        sim_A = A_sp(*values)
+        if np.all(np.real(np.linalg.eigvals(sim_A)) < 0):
+            try:
+                inv_A = np.linalg.inv(-sim_A)
+                effect = (
+                    inv_A[:, pert_idx] * sign 
+                    if pert_idx is not None else inv_A
+                )
+                positive += effect > 0
+                negative += effect < 0
+                total_simulations += 1
+            except np.linalg.LinAlgError:
+                continue
+    smat = np.where(negative > positive, -negative / n_sim, positive / n_sim)
+    smat = sp.Matrix(smat)
+    tmat = absolute_feedback_matrix(G)
+    tmat_np = np.array(tmat.tolist(), dtype=bool)
+    smat = sp.Matrix(
+        [
+            [sp.nan if not tmat_np[i, j] else smat[i, j] for j in range(n)]
+            for i in range(n)
+        ]
+    )
+    if as_abs:
+        smat = sp.Abs(smat)
+    return sp.Matrix(smat)

qmm/core/stability.py

@@ -0,0 +1,367 @@
+import numpy as np
+import pandas as pd
+import networkx as nx
+import sympy as sp
+from itertools import combinations
+from functools import cache
+from .structure import create_matrix
+from .helper import perm, get_positive, get_negative, get_weight
+
+
+def colour_test(G):
+    A = create_matrix(G, form="signed")
+    n = A.shape[0]
+    colour = {i: "black" if A[i, i] != 0 else "white" for i in range(n)}
+    if n <= 4 or "white" not in colour.values():
+        return "Fail"
+    else:
+        while "white" in colour.values():
+            progress_made = False
+            for i in [i for i, c in colour.items() if c == "white"]:
+                neighbours = [(j, colour[j]) for j in range(n) 
+                              if A[i, j] * A[j, i] < 0]
+                white_neighbours = [j for j, c in neighbours if c == "white"]
+                if not white_neighbours or any(
+                    sum(
+                        1
+                        for k in range(n)
+                        if A[j, k] * A[k, j] < 0 and colour[k] == "white"
+                    )
+                    <= 1
+                    for j in [j for j, c in neighbours if c == "black"]
+                ):
+                    colour[i] = "black"
+                    progress_made = True
+                    break
+            if not progress_made:
+                return "Pass"
+        return "Fail"
+
+
+def sign_stability(G):
+    A = sp.matrix2numpy(create_matrix(G, form="signed")).astype(int)
+    n = A.shape[0]
+    conditions = [
+        all(A[i, i] <= 0 for i in range(n)),
+        any(A[i, i] < 0 for i in range(n)),
+        all(A[i, j] * A[j, i] <= 0 for i in range(n) for j in range(n) if i != j),
+        all(len(cycle) < 3 for cycle in nx.simple_cycles(nx.DiGraph(A))),
+        np.linalg.det(A) != 0,
+    ]
+    colour_result = colour_test(G) == "Fail"
+    is_sign_stable = all(conditions) and colour_result
+    return pd.DataFrame(
+        {
+            "Test": [
+                "Condition i",
+                "Condition ii",
+                "Condition iii",
+                "Condition iv",
+                "Condition v",
+                "Colour test",
+                "Sign stable",
+            ],
+            "Definition": [
+                "No positive self-effects",
+                "At least one node is self-regulating",
+                "The product of any pairwise interaction is non-positive",
+                "No cycles greater than length two",
+                "Non-zero determinant (all nodes have at least " +
+                "one incoming and outgoing link)",
+                "Fails Jeffries' colour test",
+                "Satisfies necessary and sufficient conditions for sign stability",
+            ],
+            "Result": conditions + [colour_result] + [is_sign_stable],
+        }
+    )
+
+
+@cache
+def system_feedback(G, level=None, form="symbolic"):
+    A = create_matrix(G, form=form)
+    if level == 0:
+        return sp.Matrix([-1])
+    n = A.shape[0]
+    lam = sp.symbols("lambda")
+    p = A.charpoly(lam).as_expr()
+    if level is None:
+        fb = [-p.coeff(lam, n - k) for k in range(n + 1)]
+    else:
+        fb = [-p.coeff(lam, n - level)]
+    return sp.Matrix(fb)
+
+
+@cache
+def net_feedback(G, level=None):
+    return system_feedback(G, level=level, form="signed")
+
+
+@cache
+def absolute_feedback(G, level=None, method="combinations"):
+    A = create_matrix(G, form="signed")
+    if level == 0:
+        return sp.Matrix([1])
+    n = A.shape[0]
+    if method == "combinations":
+        A = sp.matrix2numpy(A).astype(int)
+        A = np.abs(A)
+        if level is None:
+            fb = []
+            for k in range(n + 1):
+                fb_k = sum(
+                    perm(A[np.ix_(c, c)], method="glynn")
+                    for c in combinations(range(n), k)
+                )
+                fb.append(int(fb_k))
+        else:
+            fb_k = sum(
+                perm(A[np.ix_(c, c)], method="glynn")
+                for c in combinations(range(n), level)
+            )
+            fb = [int(fb_k)]
+    elif method == "polynomial":
+        lam = sp.Symbol("lambda")
+        A_abs = sp.Matrix(sp.Abs(A) + lam * sp.eye(n))
+        P = sp.per(A_abs)
+        if level is None:
+            fb = [P.coeff(lam, n - k) for k in range(n + 1)]
+        else:
+            fb = [P.coeff(lam, n - level)]
+    return sp.Matrix(fb)
+
+
+@cache
+def weighted_feedback(G, level=None):
+    net_fb = net_feedback(G, level=level)
+    tot_fb = absolute_feedback(G, level=level)
+    return get_weight(net_fb, tot_fb)
+
+
+def hurwitz_matrix(fb, level):
+    fb_pos = fb * sp.Integer(-1)
+    if level == 0:
+        return sp.Matrix([fb_pos[0]])
+    H = sp.zeros(level, level)
+    for i in range(level):
+        for j in range(level):
+            index = 2 * j - i + 1
+            if 0 <= index < len(fb_pos):
+                H[i, j] = fb_pos[index]
+    return H
+
+
+@cache
+def feedback_metrics(G):
+    net = net_feedback(G)
+    absolute = absolute_feedback(G)
+    positive = get_positive(net, absolute)
+    negative = get_negative(net, absolute)
+    weighted = weighted_feedback(G)
+    n = len(positive)
+    levels = [f"$F_{{{i}}}$" for i in range(n)]
+
+    df = {
+        "Level": levels,
+        "Net": [net[i, 0] for i in range(n)],
+        "Absolute": [absolute[i, 0] for i in range(n)],
+        "Positive": [positive[i, 0] for i in range(n)],
+        "Negative": [negative[i, 0] for i in range(n)],
+        "Weighted": [weighted[i, 0] for i in range(n)],
+    }
+
+    return pd.DataFrame(df)
+
+
+@cache
+def hurwitz_determinants(G, level=None, form="symbolic"):
+    fb = system_feedback(G, level=None, form=form)
+    n = len(fb) - 1
+    if n > 5 and form == "symbolic":
+        raise ValueError("Limited to systems with five or fewer variables.")
+    if level is None:
+        h = hurwitz_matrix(fb, n)
+        hd = sp.Matrix([sp.det(h[:k, :k]) for k in range(0, n + 1)])
+    else:
+        h = hurwitz_matrix(fb, level)
+        hd = sp.Matrix([sp.det(h[:level, :level])])
+    return sp.Matrix(hd)
+
+
+@cache
+def net_determinants(G, level=None):
+    return hurwitz_determinants(G, level=level, form="signed")
+
+
+@cache
+def absolute_determinants(G, level=None):
+    tot_fb = absolute_feedback(G)
+    n = tot_fb.shape[0] - 1
+    h = hurwitz_matrix(tot_fb, n)
+    if level is None:
+        td = [sp.Integer(1)]
+        for k in range(1, n + 1):
+            h_k = np.array(h[:k, :k].tolist(), dtype=float)
+            td.append(sp.Abs(sp.Integer(int(perm(h_k)))))
+    else:
+        if level < 0 or level > n:
+            raise ValueError(f"Level must be between 0 and {n}")
+        if level == 0:
+            td = [sp.Integer(1)]
+        else:
+            H_k = np.array(h[:level, :level].tolist(), dtype=float)
+            td = [sp.Abs(sp.Integer(int(perm(H_k))))]
+    return sp.Matrix(td)
+
+
+@cache
+def weighted_determinants(G, level=None):
+    net_det = net_determinants(G, level=level)
+    tot_det = absolute_determinants(G, level=level)
+    wgt_det = get_weight(net_det, tot_det)
+    return wgt_det
+
+
+@cache
+def determinants_metrics(G):
+    net = net_determinants(G)
+    absolute = absolute_determinants(G)
+    weighted = weighted_determinants(G)
+    n = len(net)
+    levels = [f"$\Delta_{{{i}}}$" for i in range(n)]
+    df = {
+        "Hurwitz determinant": levels,
+        "Net": [net[i, 0] for i in range(n)],
+        "Absolute": [absolute[i, 0] for i in range(n)],
+        "Weighted": [weighted[i, 0] for i in range(n)],
+    }
+    return pd.DataFrame(df)
+
+
+@cache
+def create_model_c(n):
+    C = nx.DiGraph()
+    for i in range(n):
+        C.add_node(i)
+    for i in range(1, n):
+        C.add_edge(i - 1, i, sign=-1)
+        C.add_edge(i, i - 1, sign=1)
+    C.add_edge(n - 1, n - 1, sign=-1)
+    nx.set_node_attributes(C, "state", "category")
+    return C
+
+
+@cache
+def conditional_stability(G):
+    A = create_matrix(G, form="signed")
+    n = A.shape[0]
+    w_fb = weighted_feedback(G)
+    w_det = weighted_determinants(G, level=n - 1)[0]
+    C = create_model_c(n)
+    w_det_c = weighted_determinants(C, level=n - 1)[0]
+    ratio_C = w_det / w_det_c
+    max_fb_n = np.max(w_fb) == w_fb[-1]
+    kmax = len(w_fb) - 1 - np.argmax(w_fb[::-1])
+    is_sign_stable = sign_stability(G)["Result"].iloc[-1]
+    if is_sign_stable:
+        model_class = "Sign stable"
+    elif max_fb_n and ratio_C >= 1:
+        model_class = "Class I"
+    else:
+        model_class = "Class II"
+    stability_metrics = pd.DataFrame(
+        {
+            "Test": [
+                "Weighted feedback",
+                "Weighted determinant",
+                "Ratio to model-c system",
+                "Model class",
+            ],
+            "Definition": [
+                f"Maximum weighted feedback (level {kmax})",
+                "n-1 weighted determinant at level",
+                "Ratio to a 'model-c' type system",
+                "Class of the model based on conditional stability metrics",
+            ],
+            "Result": [
+                np.max(w_fb).evalf(2),
+                w_det.evalf(2),
+                ratio_C.evalf(2),
+                model_class,
+            ],
+        }
+    )
+    return stability_metrics
+
+
+@cache
+def simulation_stability(G, n_sim=10000):
+    A = create_matrix(G, "signed")
+    A = sp.matrix2numpy(A).astype(int)
+    n_stable = 0
+    n_unstable = 0
+    n_hurwitz_i_fail = 0
+    n_hurwitz_ii_fail = 0
+    n_hurwitz_i_only_fail = 0
+    n_hurwitz_ii_only_fail = 0
+    for _ in range(n_sim):
+        M = np.random.rand(*A.shape)
+        S = A * M
+        if np.all(np.real(np.linalg.eigvals(S)) < 0):
+            n_stable += 1
+        else:
+            n_unstable += 1
+        pc = np.poly(S)
+        hurwitz_i = np.all(pc[1:] > 0) or np.all(pc[1:] < 0)
+        n = len(pc)
+        H = np.zeros((n - 1, n - 1))
+        for i in range(1, n):
+            for j in range(1, n):
+                index = 2 * j - i
+                if 0 <= index < n:
+                    H[i - 1, j - 1] = pc[index]
+        hd = [np.linalg.det(H[: k + 1, : k + 1]) for k in range(n - 1)]
+        hurwitz_ii = np.all(np.array(hd[1:-1]) > 0)
+        if not hurwitz_i:
+            n_hurwitz_i_fail += 1
+            if hurwitz_ii:
+                n_hurwitz_i_only_fail += 1
+        if not hurwitz_ii:
+            n_hurwitz_ii_fail += 1
+            if hurwitz_i:
+                n_hurwitz_ii_only_fail += 1
+    prop_stable = n_stable / n_sim
+    prop_unstable = n_unstable / n_sim
+    prop_hurwitz_i_fail = n_hurwitz_i_fail / n_sim
+    prop_hurwitz_ii_fail = n_hurwitz_ii_fail / n_sim
+    prop_hurwitz_i_only_fail = n_hurwitz_i_only_fail / n_sim
+    prop_hurwitz_ii_only_fail = n_hurwitz_ii_only_fail / n_sim
+    sim_df = pd.DataFrame(
+        {
+            "Test": [
+                "Stable matrices",
+                "Unstable matrices",
+                "Hurwitz criterion i",
+                "Hurwitz criterion ii",
+                "Hurwitz criterion i only",
+                "Hurwitz criterion ii only",
+            ],
+            "Definition": [
+                "Proportion where all eigenvalues have negative real parts",
+                "Proportion where one or more eigenvalues have positive real parts",
+                "Proportion where polynomial coefficients are not " +
+                "all of the same sign",
+                "Proportion where Hurwitz determinants are not all positive",
+                "Proportion where only Hurwitz criterion i fails",
+                "Proportion where only Hurwitz criterion ii fails",
+            ],
+            "Result": [
+                f"{prop_stable:.2%}",
+                f"{prop_unstable:.2%}",
+                f"{prop_hurwitz_i_fail:.2%}",
+                f"{prop_hurwitz_ii_fail:.2%}",
+                f"{prop_hurwitz_i_only_fail:.2%}",
+                f"{prop_hurwitz_ii_only_fail:.2%}",
+            ],
+        }
+    )
+    return sim_df

qmm/core/structure.py

@@ -0,0 +1,120 @@
+import json
+import networkx as nx
+import sympy as sp
+from .helper import get_nodes
+
+
+def import_digraph(file_path):
+    with open(file_path, "r") as file:
+        data = json.load(file)
+    G = nx.DiGraph()
+    for node in data["nodes"]:
+        att = {k: v for k, v in node.items() if k != "id"}
+        G.add_node(node["id"], **att)
+    for edge in data["edges"]:
+        source = edge["from"]
+        target = edge["to"]
+        att = {k: v for k, v in edge.items() if k not in ["from", "to", "arrows"]}
+        arr = edge.get("arrows", {}).get("to", {})
+        if isinstance(arr, dict):
+            arr_type = arr.get("type")
+            if arr_type == "triangle":
+                att["sign"] = 1
+            elif arr_type == "circle":
+                att["sign"] = -1
+        G.add_edge(source, target, **att)
+    nx.set_node_attributes(G, "state", "category")
+    return G
+
+
+def create_matrix(G, form="symbolic", matrix_type="A"):
+    if not isinstance(G, nx.DiGraph):
+        raise TypeError("Input must be a networkx.DiGraph.")
+    if form not in ["symbolic", "signed", "binary"]:
+        raise ValueError("Invalid form. Choose 'symbolic', 'signed', or 'binary'.")
+    if matrix_type not in ["A", "B", "C", "D"]:
+        raise ValueError("Invalid matrix_type. Choose 'A', 'B', 'C', or 'D'.")
+
+    def sym(source, target, prefix):
+        return sp.Symbol(f"{prefix}_{target},{source}")
+
+    def sign(source, target, prefix):
+        if form == "symbolic":
+            return sym(source, target, prefix) * G[source][target].get("sign", 1)
+        elif form == "signed":
+            return G[source][target].get("sign", 1)
+        else:  # form == 'binary'
+            return int(G.has_edge(source, target))
+
+    def product(path):
+        effect = 1
+        for i in range(len(path) - 1):
+            effect *= sign(path[i], path[i + 1], prefix)
+        return effect
+
+    state_n = get_nodes(G, "state")
+    input_n = get_nodes(G, "input")
+    output_n = get_nodes(G, "output")
+    matrix_configs = {
+        "A": (state_n, state_n, "a", "state"),
+        "B": (state_n, input_n, "b", "input"),
+        "C": (output_n, state_n, "c", "output"),
+        "D": (output_n, input_n, "d", "input"),
+    }
+    rows, cols, prefix, category = matrix_configs[matrix_type]
+    matrix = sp.zeros(len(rows), len(cols))
+    for i, target in enumerate(rows):
+        for j, source in enumerate(cols):
+            if matrix_type == "A":
+                if G.has_edge(source, target):
+                    matrix[i, j] = sign(source, target, prefix)
+            else:
+                paths = nx.all_simple_paths(G, source, target)
+                valid = [
+                    p
+                    for p in paths
+                    if all(G.nodes[n]["category"] == category for n in p[1:-1])
+                ]
+                matrix[i, j] = sum(product(path) for path in valid)
+    return matrix
+
+
+def create_equations(G, form="state", density_independent=None):
+    if not isinstance(G, nx.DiGraph):
+        raise TypeError("Input must be a networkx.DiGraph.")
+    A = create_matrix(G, form="symbolic", matrix_type="A")
+    B = create_matrix(G, form="symbolic", matrix_type="B")
+    C = create_matrix(G, form="symbolic", matrix_type="C")
+    D = create_matrix(G, form="symbolic", matrix_type="D")
+    state_n = get_nodes(G, "state")
+    input_n = get_nodes(G, "input")
+    output_n = get_nodes(G, "output")
+    x = sp.Matrix([sp.Symbol(f"x_{i}") for i in state_n])
+    u = sp.Matrix([sp.Symbol(f"u_{i}") for i in input_n]) if input_n else None
+    y = sp.Matrix([sp.Symbol(f"y_{i}") for i in output_n]) if output_n else None
+    if density_independent is None:
+        k = sp.zeros(A.shape[0], 1)
+    else:
+        if len(density_independent) != A.shape[0]:
+            raise ValueError(f"The length of k must be equal to {A.shape[0]}")
+        k = sp.Matrix(density_independent)
+    state_equations = x.multiply_elementwise(A * x + k)
+    if B.shape[1] > 0 and u is not None:
+        state_equations += B * u
+    output_equations = None
+    if C.shape[0] > 0:
+        output_equations = C * x
+        if D.shape[1] > 0 and u is not None:
+            output_equations += D * u
+    if form == "vector":
+        return A, B, C, D, x, u, y, k
+    elif form == "state":
+        return state_equations
+    elif form == "output":
+        if output_equations is None:
+            print("No output equations available.")
+        return output_equations
+    elif form == "jacobian":
+        return state_equations.jacobian(x)
+    else:
+        raise ValueError("Choose 'vector', 'state', 'output' or 'jacobian'.")

qmm_core-0.2.2.dist-info/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+qmm/__init__.py,sha256=SVnmNEHf91LBaitoJ2H_sJlcoEGvN6ocSy2PZAq68O4,1940
+qmm/core/helper.py,sha256=9EsVxZIGw3ZObW2aqDy5W2x8auDLv5C7ucemI7KBRdY,10198
+qmm/core/prediction.py,sha256=xo4XqgBECkrx4QmEJVZmlSclkTRzUz9jAUwqEs-d1KM,2315
+qmm/core/press.py,sha256=wWXUDSRuL4xNbUof3C0MGz1dXv71NXsvbwctS7_W6NQ,3958
+qmm/core/stability.py,sha256=JDuzumGFl3Ul6nodBfhyF5Ccadd3r4SZcoPsdU4bXHs,11764
+qmm/core/structure.py,sha256=CIaSUhdN7eb1Nl6nMREF7RsO2w3Oy9FWJYcVruw5IYQ,4598
+qmm_core-0.2.2.dist-info/LICENSE,sha256=9BC7XxEa_nD9uc8dHjJG-FuPTA0DllmuJTOPAUYJtrc,1527
+qmm_core-0.2.2.dist-info/METADATA,sha256=cdm4Kipj266EmF5ZMY4QXOCFnq79YU_r1hVaJ0NZkRU,3654
+qmm_core-0.2.2.dist-info/WHEEL,sha256=cVxcB9AmuTcXqmwrtPhNK88dr7IR_b6qagTj0UvIEbY,91
+qmm_core-0.2.2.dist-info/top_level.txt,sha256=Nl8juSbthZpsufyisqeDeXVq1jnpHeADFAW0_vN85cg,4
+qmm_core-0.2.2.dist-info/RECORD,,

qmm_core-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (74.1.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

qmm_core-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+qmm