Metadata-Version: 2.1
Name: mmodel
Version: 0.3.0
Summary: Modular modeling framework for nonlinear scientific models
Home-page: https://github.com/peterhs73/MModel
License: BSD-3-Clause
Author: Peter Sun
Author-email: hs859@cornell.edu
Maintainer: Peter Sun
Maintainer-email: hs859@cornell.edu
Requires-Python: >=3.6
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Provides-Extra: docs
Provides-Extra: test
Requires-Dist: graphviz (>=0.16)
Requires-Dist: h5py (>=3.6.0)
Requires-Dist: nbsphinx (>=0.8.8,<0.9.0); extra == "docs"
Requires-Dist: networkx (>=2.8.3)
Requires-Dist: pytest (>=7.1.1); extra == "test"
Requires-Dist: pytest-cov (>=3.0.0); extra == "test"
Requires-Dist: sphinx (>=4.5.0,<5.0.0); extra == "docs"
Requires-Dist: sphinx-book-theme (>=0.3.2,<0.4.0); extra == "docs"
Requires-Dist: tox (>=3.24.5)
Project-URL: Repository, https://github.com/peterhs73/MModel
Description-Content-Type: text/x-rst

MModel
======

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. The package
is well tested with 100 % coverage.

Quickstart
----------

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

.. code-block:: python

    from mmodel import ModelGraph, Model, MemHandler
    import math

    def func_a(x, y):
        return x + y

    def func_b(sum_xy, base):
        return math.log(sum_xy, base)

    def func_c(sum_xy, log_xy):
        return sum_xy * log_xy

    # create graph links

    grouped_edges = [
        ("func a", ["func b", "func c"]),
        ("func b", "func c"),
    ]

    node_objects = [
        ("func a", func_a, ["sum_xy"]),
        ("func b", func_b, ["log_xy"]),
        ("func c", func_c, ["result"]),
    ]

    graph = ModelGraph(name="Example")
    graph.add_grouped_edges_from(grouped_edges)
    graph.set_node_objects_from(node_objects)

    example_func = Model(graph, handler=MemHandler)

    >>> print(example_func)
    Example model
      signature: base, x, y
      returns: result
      handler: MemHandler
      modifiers: none

    >>> example_func(2, 5, 3) # (5 + 3)log(5 + 3, 2)
    24.0

The resulting ``example_func`` is callable.

One key feature of ``mmodel`` is modifiers, which modify callables post
definition. To loop the "base" parameter.

.. code-block:: python 

    from mmodel import subgraph_by_parameters, modify_subgraph, loop_modifier

    subgraph = subgraph_by_parameters(graph, ["base"])
    loop_node = Model(subgraph, MemHandler, [loop_modifier("base")])
    looped_graph = modify_subgraph(graph, subgraph, "loop node", loop_node)
    looped_model = Model(looped_graph, handler=MemHandler)

    >>> print(looped_model)
    Example model
      signature: base, x, y
      returns: result
      handler: MemHandler
      modifiers: none
    
    >>> looped_model([2, 4], 5, 3) # (5 + 3)log(5 + 3, 2)
    [24.0, 12.0]


Modifiers can also be added to the whole model or a single node.

To draw the graph or the underlying graph of the model:

.. code-block:: python
    
    graph.draw()
    example_func.draw()

Installation
------------

Graphviz installation
^^^^^^^^^^^^^^^^^^^^^

To view the graph, Graphviz needs to be installed:
`Graphviz Installation <https://graphviz.org/download/>`_
For windows installation, please choose "add Graphviz to the
system PATH for all users/current users" during the setup.

``mmodel`` installation
^^^^^^^^^^^^^^^^^^^^^^^

.. code-block::

    pip install mmodel

Development installation
^^^^^^^^^^^^^^^^^^^^^^^^
``mmodel`` uses `poetry <https://python-poetry.org/docs/>`_ as
the build system. The package works with both pip and poetry
installation. 

To install test and docs, despondencies run::

    pip install .[test] .[docs]

(For ``zsh`` shell, run ``pip install ".[test]"``)

To run the tests, run::

    pytest

To run the tests in different python environments (py38, py39,
coverage and docs)::

    tox

To create the documentation, run under the "/docs" directory::

    make html

