mmodel 0.5.1

Quickstart

To create a nonlinear model that has the result of (x + y)log(x + y, base):

from mmodel import ModelGraph, Model, MemHandler
import math
import numpy as np

def func(sum_xy, log_xy):
    """Function that adds a value to the multiplied inputs."""
    return sum_xy * log_xy + 6

The graph is defined using grouped edges (the networkx syntax of edge the definition also works.)

# create graph edges
grouped_edges = [
    ("add", ["log", "function node"]),
    ("log", "function node"),
]

The functions are then added to node attributes. The order of definition is node_name, node_func, output, input (if different from original function), and modifiers.

# define note objects
node_objects = [
    ("add", np.add, "sum_xy", ["x", "y"]),
    ("log", math.log, "log_xy", ["sum_xy", "log_base"]),
    ("function node", func, "result"),
]

G = ModelGraph(name="example_graph")
G.add_grouped_edges_from(grouped_edges)
G.set_node_objects_from(node_objects)

To define the model, the name, graph, and handler need to be specified. Additional parameters include modifiers, descriptions, and returns lists. The input parameters of the model are determined based on the node information.

example_model = Model("example_model", G, handler=(MemHandler, {}), description="Test model.")

The model behaves like a Python function, with additional metadata. The graph can be plotted using the draw method.

>>> print(example_model)
example_model(log_base, x, y)
returns: z
graph: example_graph
handler: MemHandler()

Test model.

>>> example_model(2, 5, 3) # (5 + 3)log(5 + 3, 2) + 6
30.0

>>> example_model.draw()

The resulting graph contains the model metadata and detailed node information.

One key feature of mmodel that differs from other workflow is modifiers, which modify callables post definition. Modifiers work on both the node level and model level.

Example: Using modifier and graph to loop the nodes that require the “log_base” parameter.

from mmodel import loop_modifier

H = G.subgraph(inputs=["log_base"])
loop_node = Model(
    "loop_submodel",
    H,
    handler=(MemHandler, {}),
    modifiers=[(loop_modifier, {"parameter": "log_base"})],
)
looped_G = G.replace_subgraph(H, "loop_node", loop_node, output="looped_z")
looped_model = Model("looped_model", looped_G, loop_node.handler)

We can inspect the loop node as well as the new model.

>>> print(loop_node)
loop_submodel(log_base, sum_xy)
returns: z
graph: example_graph
handler: MemHandler()
modifiers:
  - loop_modifier('log_base')

>>> print(looped_model)
looped_model(log_base, x, y)
returns: looped_z
graph: example_graph
handler: MemHandler()

>>> looped_model([2, 4], 5, 3) # (5 + 3)log(5 + 3, 2) + 6
[30.0, 18.0]

Use the draw method to draw the graph. There are three styles “plain”, “short”, and “full”, which differ by the level of detail of the node information. A graph output is displayed in Jupyter Notebook or can be saved using the export option.

G.draw(style="short")
example_model.draw(style="plain", export="example.pdf") # default to draw_graph

Installation

pip install mmodel

conda install -c conda-forge pygraphviz

pip install .[test] .[docs]

tox

make html