MModel is a lightweight and modular model-building framework for small-scale and nonlinear models. The package aims to solve scientific program prototyping and distribution difficulties, making it easier to create modular, fast, and user-friendly packages.
For using mmodel in a complex scientific workflow, please refer to the mrfmsim on how mmodel improves the development of magnetic resonance force microscopy (MRFM) experiments.
To create a nonlinear model that has the result of (x + y)log(x + y, base):
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.)
from mmodel import ModelGraph, Model, MemHandler
# 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: Use loop_input
modifier on the graph to loop the nodes that require the "log_base" parameter.
from mmodel import loop_input
H = G.subgraph(inputs=["log_base"])
H.name = "example_subgraph"
loop_node = Model("submodel", H, handler=MemHandler)
looped_G = G.replace_subgraph(
H,
"loop_node",
loop_node,
output="looped_z",
modifiers=[loop_input("log_base")],
)
looped_G.name = "looped_graph"
looped_model = Model("looped_model", looped_G, loop_node.handler)
We can inspect the loop node as well as the new model.
>>> print(looped_model)
looped_model(log_base, x, y)
returns: looped_z
graph: looped_graph
handler: MemHandler()
>>> print(looped_model.node_metadata("loop_node"))
submodel(log_base, sum_xy)
return: looped_z
functype: mmodel.Model
modifiers:
- loop_input('log_base')
>>> 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 "verbose", 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
To view the graph, Graphviz needs to be installed: Graphviz Installation For windows installation, please choose "add Graphviz to the system PATH for all users/current users" during the setup.
pip install mmodel
MModel uses poetry as the build system. The package works with both pip and poetry installation. For macos systems, sometimes brew install results in unexpected installation path, it is recommended to install with conda:
conda install -c conda-forge pygraphviz
To install test and docs, despondencies run:
pip install .[test] .[docs]
To run the tests in different python environments and cases (py38, py39, py310, py311, coverage and docs):
tox
To create the documentation, run under the "/docs" directory:
make html
Author: Marohn-Group
Source: https://github.com/Marohn-Group/mmodel
License: View license