betaFeedback

WorksPhysics and Astronomy

mmodel: A workflow framework to accelerate the development of experimental simulations

Abstract

Simulation has become an essential component of designing and developing scientific experiments. The conventional procedural approach to coding simulations of complex experiments is often error-prone, hard to interpret, and inflexible, making it hard to incorporate changes such as algorithm updates, experimental protocol modifications, and looping over experimental parameters. We present mmodel, a framework designed to accelerate the writing of experimental simulation packages. mmodel uses a graph-theory approach to represent the experiment steps and can rewrite its own code to implement modifications, such as adding a loop to vary simulation parameters systematically. The framework aims to avoid duplication of effort, increase code readability and testability, and decrease development time.

Introduction

Scientific experiments are becoming ever more complex, with multiple interconnected components. Experiments thus often require simulation code to explore the feasibility, optimize experimental parameters, and extract information from experimental results. In fields such as mass spectrometry,[1, 2] X-ray spectroscopy,[3, 4, 5] and magnetic resonance force microscopy (MRFM),[6, 7, 8, 9, 10] experiments are expensive and time-consuming. In these and other fields, simulation has become crucial to experimental design and hardware development. For example, research groups in the MRFM field employ a wide variety of experimental setups, materials, and spin-detection protocols. In order to design experiments and validate results across laboratories, we need simulation codes that cover all possible setups, materials, and protocols. The code should be fast, readable, reliable, modular, and expandable.

The typical approach to experimental simulation is to create one-off simulations for each experiment of interest.[11] Unfortunately, the code needs to be rewritten when we modify the experiment or implement a loop to vary parameters efficiently. These practices result in simulations that contain large amounts of duplicated code and are often unreadable. Moreover, the one-off nature of the code impedes reproducibility and leads to errors due to a lack of testing and annotation;[11, 12] coding errors lead to incorrect publication results in many scientific fields.[13, 14, 15] A new approach is needed to develop modular, expandable, testable, and readable simulation code.

This paper introduces the mmodel package that provides a framework for coding experiments simulations. mmodel employs a graph-based representation of the experimental components, a method popular in scientific workflows design.[16, 17] The framework prioritizes the prototyping phase of the development by allowing modification to the simulation model post-definition, which most workflow systems cannot achieve. In addition, we show that existing projects can easily migrate to the mmodel framework. Section II introduces a simple representative physics experiment and shows how mmodel’s graph-theory-based simulation approach facilitates experimental parameter exploration, experimental result validation, and the debugging process. Section III compares mmodel to other popular scientific workflows and discusses the advantages of mmodel in the prototyping phase of development. Appendix A summarizes the mmodel API and presents example scripts to define, modify and execute the experiment discussed in Section II.

Scientific experiment prototype

Consider the following contrived experiment investigating the force exerted on a moving magnet by a charged sample. The magnet is spherical and is attached to a micro-cantilever that oscillates in the xx direction, shown in Figure 1. The force on a moving charge qq by an electric field EE and a magnetic field BB can be calculated using the Lorentz force law.[18]

Figure 1. Example setup. (a) The isometric view. A magnet is attached to a micro-cantilever. A charged sample is located below the magnet. (b) The side view. The cantilever oscillates in the xx direction, and the magnet is xmx_{\mathrm{m}} away from the equilibrium position. The ithi^{\mathrm{th}} sample charge QiQ_i is located at si=(xi,yi,zi)\boldsymbol{s}_i=(x_i,y_i,z_i).

F=q(E+v×B).(1)F = q(E + \boldsymbol{v} \times B). \tag*{(1)}

Using the magnet as the frame of reference, the problem is equivalent to calculating the sum of the force exerted on a fixed magnet by moving charges traveling through the magnet’s magnetic field.[19]

In our contrived experiment, the velocity has only an xx component, vxv_x. We can approximate the cantilever oscillation as simple harmonic motion in the xx direction. Given the cantilever frequency ff and amplitude AA, the magnet displacement xmx_m (measured relative to the equilibrium position) and the velocity vxv_x are

xm(t)=Acos⁡(ωt)(2)x_m(t)=A\cos(\omega t) \tag*{(2)}
vx(t)=−ωAsin⁡(ωt)(3)v_x(t)=-\omega A\sin(\omega t) \tag*{(3)}

where ω=2πf\omega=2\pi f and xm∈(−A,A)x_m\in(-A,A). We assume the magnet’s origin at the equilibrium position is (0,0,0)(0,0,0). We want to calculate the force on the magnet when the displacement is xmx_m. The instantaneous magnet velocity vxv_x at the position of motion (xm,0,0)(x_m,0,0) can be calculated as follows:

vx(xm)=±2πfA2−xm2.(4)v_x(x_m)=\pm2\pi f\sqrt{A^2-x_m^2}. \tag*{(4)}

The sphere’s magnetic field in the yy and zz directions at the ith{i}^{\text{th}} charge’s position si=(xi,yi,zi)\boldsymbol{s}_i=(x_i,y_i,z_i), By(si)B_y(\boldsymbol{s}_i) and Bz(si)B_z(\boldsymbol{s}_i), can be calculated using

Bz(si)=μ0Ms3(3Zi2Ri5−1Ri3)(5)B_z(\boldsymbol{s}_i)=\frac{\mu_0M_s}{3}\left(3\frac{Z_i^2}{R_i^5}-\frac{1}{R_i^3}\right) \tag*{(5)}
By(si)=μ0Ms(YiZiRi5),(6)B_y(\boldsymbol{s}_i)=\mu_0M_s\left(\frac{Y_iZ_i}{R_i^5}\right), \tag*{(6)}

with μ0\mu_0 the vacuum permeability; MsM_s the magnet saturation magnetization; rr the magnet radius; Xi=(xi−xm)/rX_i=(x_i-x_m)/r, Yi=yi/rY_i=y_i/r, and Zi=zi/rZ_i=z_i/r the reduced charge coordinates; and Ri=Xi2+Yi2+Zi2R_i=\sqrt{X_i^2+Y_i^2+Z_i^2} a reduced distance. It is important to note that each point charge can induce an image charge in the magnet, resulting in an additional electric and magnetic field.[18] We ignore the fields generated based on this effect for simplicity.

Finally, without the external field EE, the forces exerted on the magnet in the yy and zz direction, FyF_y and FzF_z, by a set of NN discrete charges QiQ_i can be calculated by summing the forces exerted by the individual charges:

Fy(xm)=vx(xm)∑i=1NQiBz(si,xm)(7)F_y(x_m)=v_x(x_m)\sum_{i=1}^{N}Q_iB_z(\boldsymbol{s}_i,x_m) \tag*{(7)}
Fz(xm)=−vx(xm)∑i=1NQiBy(si,xm),(8)F_z(x_m)=-v_x(x_m)\sum_{i=1}^{N}Q_iB_y(\boldsymbol{s}_i,x_m), \tag*{(8)}

where Qi=Q(si)Q_i=Q(\boldsymbol{s}_i) is the charge of the ith{i}^{\text{th}} sample charge located at si\boldsymbol{s}_i. In the pseudocode, we use grid to represent the collection of charge positions. The variables are shown in Table I.

variabledescription
ffcantilever frequency
AAcantilever amplitude
vxv_xinstantaneous magnet motion velocity
xmx_mmagnet position in the xx direction
rrmagnet radius
μ0\mu_0vacuum permeability
MsM_smagnet saturation magnetization
ByB_ymagnet magnetic field in the yy direction
BzB_zmagnet magnetic field in the zz direction
qqpoint charge
QiQ_icharge of the ith{i}^{\text{th}} sample charge
si\boldsymbol{s}_ilocation of the ith{i}^{\text{th}} sample charge, (xi,yi,zi)(x_i,y_i,z_i)
gridcollection of sample charge positions
FyF_yforce on the magnet in the yy direction
FzF_zforce on the magnet in the zz direction

Table 1. List of the Lorentz force law model variables calculating the forces on moving magnet from a charge distribution.

Algorithm 1: Procedural program of the Lorentz force law model calculating the forces on moving magnet from a charge distribution.

Function Experiment (A, f, grid, μ₀, Mₛ, Q, r, xₘ):
    vₓ ← Vxfunc(f, A, xₘ)
    B𝓏 ← Bzfunc(μ₀, Mₛ, r, grid, xₘ)
    Bᵧ ← Byfunc(μ₀, Mₛ, r, grid, xₘ)
    for x, y, z in grid do
        Fᵧ,grid [x, y, z] ← Q[x, y, z] × vₓ × B𝓏[x, y, z]
        F𝓏,grid [x, y, z] ← −Q[x, y, z] × vₓ × Bᵧ[x, y, z]
    end
    Fᵧ ← sum(Fᵧ,grid)
    F𝓏 ← sum(F𝓏,grid)
    return Fᵧ, F𝓏

Procedural Approach

Conventionally, simulations use a procedural approach that executes the experiment in steps. One procedural approach to calculating the force on the point charge is to group the calculation by component. We use Bzfunc, Byfunc, Vxfunc, Fyfunc, and Fzfunc to denote the respective calculations. Here we first calculate the components vxv_x, BxB_x, and ByB_y. The second step is to calculate FyF_y and FzF_z based on the values of QQ, vxv_x, BzB_z, ByB_y.

In the calculation, we step through the grid points to calculate the effective force at each point of the charge distribution, and we sum all the force values to obtain the total force acting on the cantilever. The algorithm is shown in Alg. 1. In the prototyping process, the above calculations can be packaged into a function or a script, with the inputs of the magnet, cantilever, and grid as input parameters and the yy- and zz-direction forces as outputs.

mmodel graph-theory approach

Alternatively, we can represent the process flow in a directed acyclic graph (DAG) G=(V,E)G=(V,E), with nodes VV as the experimental steps and edges EE as the data flow. A DAG is a directed graph with no directed cycles. A DAG has at least a topological ordering, where for all the edges (u,v)(u,v), the parent node uu is always positioned before the child node vv. With this approach, we create a graph representing the experiment and simulation process and execute the nodes in topological order while managing the intermediate value flows. In mmodel, each process is a Python callable.

Here we divide the experiment into five nodes, named by their output: Vx, Bz, By, Fy, and Fz. Each node corresponds to its respective functions, resulting in a graph G={V,E}G=\{V,E\}, where V={Vx,Bz,By,Fy,Fz}V=\{\mathrm{Vx},\mathrm{Bz},\mathrm{By},\mathrm{Fy},\mathrm{Fz}\} and E={(Bz,Fy),(By,Fz),(Vx,Fy),(Vx,Fz)}E=\{(\mathrm{Bz},\mathrm{Fy}),(\mathrm{By},\mathrm{Fz}),(\mathrm{Vx},\mathrm{Fy}),(\mathrm{Vx},\mathrm{Fz})\}, as shown in Figure 2. Each node takes input parameters externally or from its parent node. The graph is then converted into a function by defining the method of execution of the nodes in the topological ordering. The ordering ensures that the parent node of an edge is always executed first.

Figure 2. mmodel graph-theory representation of the Lorentz force law model calculating the forces on a moving magnet from a charge distribution.

One topological ordering for graph GG is [Bz, By, Vx, Fy, Fz]. To direct the data flow, we can store the intermediate value of vxv_x, BzB_z, and ByB_y calculated by the corresponding nodes. These intermediate values can be stored internally in memory or externally on disk. The function returns the output of the two terminal nodes, Fy and Fz.

Algorithm 2: Function to create a looped subgraph within a given graph using the mmodel graph-theory approach.
Function LoopMod(G, loopParam):
// G is the original graph
H←H \gets subgraph(G, loopParam)
// nodes with loopParam as input parameter and their child nodes
loopFunc ←\gets loopmodel(H, loopParam)
// convert the graph into a function with added loop
loopG ←\gets replace(G, H, loopFunc)
// replace the subgraph H in G with a new node and map loopFunc to it
return loopG

Table 2. Algorithm 2: Function to create a looped subgraph within a given graph using the mmodel graph-theory approach.

Experimental exploration: Investigate the effect of different cantilever frequencies

To investigate the effect of cantilever frequency ff over the forces on the charge, we want to loop through ff values and examine the resulting changes in the force acting on the cantilever. Since calculating ByB_y and BzB_z does not depend on the ff parameter, the most efficient simulation is to loop only the Vxfunc, Fyfunc, and Fzfunc calculations. For the procedural approach, a new function must be written by modifying the original experiment source code to add loops to the Vxfunc subsection of the code.

However, the graph-theory approach can achieve this looping result without modifying the original code. Adding the loop to the workflow can be achieved in four steps. First, we create a subgraph, H={V={Vx,Fy,Fz},E={(Vx,Fy),(Vx,Fz)}}H=\{V=\{\mathrm{Vx},\mathrm{Fy},\mathrm{Fz}\},E=\{(\mathrm{Vx},\mathrm{Fy}),(\mathrm{Vx},\mathrm{Fz})\}\}, that excludes the By and Bz nodes from the original graph. Second, we convert the subgraph into a function with the additional loop step. Third, we replace the subgraph with a single node in the original graph and map it to the subgraph function. The new graph is shown in Figure 3, where floopfunc is the function that loops through the f values. Last, the newly obtained graph is converted into a new experimental function. The process can be combined into a single function, shown in Alg. 2, and applies to all graphs defined using mmodel’s graph definition. Importantly, these steps can be automated, requiring only a one-line code modification to implement parameter looping (see A 8).

Figure 3. mmodel graph-theory representation of the Lorentz force law model with the frequency ff loop node. (a) The new mmodel graph with subgraph substituted with a loop node, (b) ff loop node model graph.

Algorithm 3: Function to add Monte Carlo fitting step to a given graph using the mmodel graph-theory approach.

Function SampleMod(G, iterParam, condition):
    // G is the original graph
    H ← subgraph(graph, iterParam)
    // nodes with iterParam as input parameter and their child nodes
    subgraphFunc ← model(H, iterParam)
    // convert the graph into a function
    sampleFunc ← MonteCarlo(subgraphFunc, result, iterParam, condition)
    // iterate through values of iterParam against the experimental result with Monte Carlo sampling and terminate based on the condition
    sampleG ← replace(G, H, sampleFunc)
    // replace the subgraph H in G with a new node and map sampleFunc to it
    return sampleG

Experimental validation: Determine the cantilever amplitude

In an experiment, the cantilever is driven at its resonance frequency, and the cantilever amplitude AA can be measured by the position detector. Suppose we have measured FyF_y and FzF_z and want to use these values to validate the amplitude value. In a procedural approach, a function is written to iterate through samplings (i.e., Monte Carlo samplings) of AA values until the simulated forces agree with the experiment (within a specified error). Similar to § 1.1 C, only the Vxfunc, Fyfunc, and Fzfunc depend on AA.

With the graph-theory approach, we can create a function that iterates through given parameter values until the termination condition is met. The function SampleMod that creates a new graph with the Monte Carlo fitting process is shown in Alg. 3. For the example scenario, the subgraph containing the Vx, Fy, and Fz nodes is converted into a function. The MonteCarlo function takes the subgraph function as an input and outputs the optimal offset value.

Debugging: Investigate intermediate values

In a prototyping process, debugging is crucial; common issues include data value or format errors. Sometimes we want to inspect the intermediate results, such as the vxv_x or FyF_y values. Conventionally, this inspection is done by adding print or logging statements — a significant effort.

Debugging becomes more straightforward with graphs: we can obtain the subgraph that outputs the desired intermediate results. The subgraph excludes unnecessary calculations, which makes it very efficient computationally. For example, we can obtain the subgraph H={V={Bz,Vx,Fy},E={(Bz,Fy),(Vx,Fy)}}H = \{V = \{\mathrm{Bz},\mathrm{Vx},\mathrm{Fy}\}, E = \{(\mathrm{Bz},\mathrm{Fy}),(\mathrm{Vx},\mathrm{Fy})\}\} that only includes the Fy node and its parents, shown in Figure 4. Additionally, since the process controls the output of the nodes, we can output the intermediate value alongside the original output. Alternatively, we can

Figure 4. Subgraph that only outputs FyF_y value based on the Lorentz force law model graph.

modify and add nodes to the graph to achieve additional functionality, such as plotting, shown in Figure 5.

Figure 5. Graphs with added plotting functionality based on the Lorentz force law model. (a) Add a node that plots By value to the graph, (b) modify the By node to add plotting functionality with calculation.

Discussion

The last two decades have seen an explosion of data in science and the data-driven science that comes with it. Scientific workflows become useful tools for managing and analyzing data, freeing domain experts from much tedious programming.[16, 17] There are various popular packages and software that facilitate the simulation of scientific experiments, such as Pegasus,[20] Kepler,[21, 22] AiIDA,[23] Dask,[24] and Pydra.[25] These packages operate at different levels of complexity. For example, Pegasus, Kepler, and AiIDA focus on complete data pipeline management, while Dask and Pydra focus on data analysis. However, these packages are most suited and optimized for upscaling scientific analysis with well-defined models. In our MRFM experiments, we constantly update the signal calculation algorithm and continuously loop over parameters and protocols to decide among experimental protocols and determine the optimal experimental conditions. With the growing number of changes to the simulation code, neither the procedural approach nor the existing scientific workflow package suits the development process. The difficulty in maintaining the simulation package inspired the creation of mmodel, which aims to reduce code duplication and provide automated solutions to simulation updates.

As highlighted in the § 1.1, mmodel solves four issues when coding experimental simulations. First, the framework reduces code duplication and makes it easy to update subsections of the simulations. mmodel separates the code definition into three parts: function, graph, and model, shown in Figure 6. The functions describe the theoretical calculation of the experimental steps. The graphs describe the steps of the experiments, and the model defines the execution process. This separation makes it easy to only change or update one part of the process without modifying the other two. For example, in § 1.1, if we wanted to update the calculation of vxv_x, only the VxFunc function would need to be updated. In the prototyping phases, these changes often happen due to theory and algorithm updates and bug fixes. The code reduction resulting from using mmodel requires fewer tests, which speeds up the development process. Second, mmodel simplifies experiment parameters testing. The graph in mmodel is interactive, and all node objects are Python functions. There is no additional decorator required during the function definition step. This design allows defining graphs with existing functions, such as Python built-in or Numpy-package functions. In addition, using functions as node objects extends the capability of the execution process. For example, a special function can be defined to identify subgraphs and create loops for a specific parameter. Our function node implementation extends the traditional capability of the DAG, which cannot contain cycles. We can write special functions to modify a process or a group of processes, such as the LoopMod function in Alg. 2, which can loop a given parameter for all the graphs defined using mmodel. Once these special functions are written, users can apply them directly to their graphs. Third, mmodel optimizes runtime performance during the prototyping process. For example, mmodel provides an execution method that optimizes memory—mmodel.MemHandler—by keeping a reference count of the times intermediate parameters are needed by the child nodes. Once all child nodes have accessed the value, the value is deleted. Another built-in execution method—mmodel.H5Handler—optimizes runtime memory by storing intermediate values in an H5DF file. Additionally, debugging using the partial graphs or outputs of the intermediate value speeds up the prototyping cycle. Fourth, mmodel improves the readability of the code by providing a visual graph representation of the experiment with rich metadata.

Figure 6. mmodel workflow definition steps. Modifiers can be applied to nodes and models. The graph defines the experimental steps, and the model defines the execution method.

mmodel is advantageous over the other workflow systems in the prototyping phase. The existing scientific workflow packages are designed for well-defined models, making the computing steps definition well-structured. As a result, the API is restrictive for modifying existing workflows and defining processes outside the package’s scope. Prototyping these packages creates unnecessarily complicated code and has a high learning curve. For example, Pegasus and Kepler require developers to define the functions and graphs using a GUI with a domain-specific language. AiiDA, Dask, and Pydra require function definition with package-specific Python decorators and special node classes. The function and graph definition cannot be easily transferred to another package due to their domain-specific approach. These packages provide a limited ability to modify the graph post definition. For example, to add loop modification, they must either be written into the graph using a special node that directs the parameter inputs (Pegasus, Pydra) or built into the model (Kepler, AiiDA, Dask). They cannot be added to the already-defined graph. This implementation prevents post-interaction at the graph or model level. Any modification to the simulation process requires a completely new workflow. In contrast, mmodel is designed to be lightweight and flexible. Each part of the graph and model definition process allows for customization. For example, a new execution process can be written with the mmodel.handler API. The implementation also allows existing packages to use the framework easily with minimal adjustments to existing functions. The drawback of the mmodel’s function-first approach is that sub-operation modification creates nested graphs and operations, making it difficult to upscale if many modification steps are required. However, we believe the resulting modest increase in computational complexity is a reasonable compromise at the prototyping stage.

We believe mmodel fills the void of a fast, reproducible, and general-purpose scientific workflow framework for simulating complex experiments. mmodel is written in Python with minimal API restrictions, making the framework excellent for building on or migrating existing Python codes. The graph representation of the experiment and the associated rich metadata helps with communication among collaborators. The flexibility and extendability allow code optimization and easy unit testing, reducing errors and accelerating code development to simulate complicated experiments.

Future Directions

In future versions, we would like to provide more graph execution methods that optimize performance and profilers that provide execution analysis. Additionally, we would like to add adaptors that can convert mmodel graphs to other popular workflow frameworks. We encourage scientists and developers to contribute to the project. The mmodel version 0.6 is available at the repository: https://github.com/marohn-group/mmodel and the documentation is available at https://marohn-group.github.io/mmodel-docs/. The project has 100% unit test coverage and is open-source under the 3-Clause BSD License.

Acknowledgements

Research reported in this publication was supported by Cornell University, the Army Research Office under Award Number W911NF-17-1-0247, and the National Institute Of General Medical Sciences of the National Institutes of Health under Award Number R01GM143556. The content of this manuscript is solely the responsibility of the authors and does not necessarily represent the official views of Cornell University, the U.S. Army Research Office, or the National Institutes of Health.

MModel API

We show how to build and interact with the model using the example in § 1.1.

Define Functions

The first step is to define the five functions of the calculation process, shown in Lst. 1. Note that for FyF_y and FzF_z calculations, instead of looping all grid positions, we calculate all the forces in the grid points at once using matrix multiplication of QQ and ByB_y matrices and sum the values of all grid points. The approach is more efficient with libraries optimized for array programming, such as Numpy.[26] Here we only calculate the force on the magnet when it moves in the positive xx direction. For the numerical simulation, we approximate the charge distribution QQ in a rectangular prism grid defined by the parameter grid.

import math
import numpy as np


def Bzfunc(mu0, Ms, r, grid, xm):
    """Magnetic field in the z direction.

    :param float mu0: vacuum permeability
    :param float Ms: magnet saturation
    magnetization
    :param float r: magnet radius
    :param np.ndarray grid: generated by np.ogrid
    , np.mgrid,
        or np.meshgrid with the shape of (3, x,
    y, z)
    :param int xm: instantaneous magnet position
        in
        x direction

    :return: Bz at the relative magnetic-charge
    position
    :rtype: np.ndarray
    """
    X = (grid[0] - xm) / r
    Y = grid[1] / r
    Z = grid[2] / r
    R = np.sqrt(X**2 + Y**2 + Z**2)
    Bz = mu0 * Ms / 3 * (3 * Z**2 / R**5 - 1 / R
**3)
    return Bz

def Byfunc(mu0, Ms, r, grid, xm):
    """Magnetic field in the y direction.

    :param float mu0: vacuum permeability
    :param float Ms: magnet saturation
    magnetization
    :param float r: magnet radius
    :param np.ndarray grid: generated by np.ogrid
    , np.mgrid,
        or np.meshgrid with the shape of (3, x,
    y, z)
    :param int xm: instantaneous magnet position
        in
        x direction

    :return: By at the relative magnetic-charge
    position
    :rtype: np.ndarray
    """
    X = (grid[0] - xm) / r
    Y = grid[1] / r
    Z = grid[2] / r
    R = np.sqrt(X**2 + Y**2 + Z**2)
    By = mu0 * Ms * (Y * Z / R**5)
    return By

def Vxfunc(f, A, xm):
    """Magnet velocity at position xm.

    :param float f: cantilever frequency
    :param float A: cantilever amplitude
    :param float xm: instantaneous magnet
    position in the
        x direction

    :return: instantaneous magnet velocity at
    position xm
    :rtype: float
    """
    omega = 2 * math.pi * f
    vx = omega * A * math.sqrt(A**2 - xm**2)
    return vx

def Fyfunc(Q, vx, Bz):
    """Force on the magnet in the y direction.

    :param np.ndarray Q: charge distribution
    :param float vx: instantaneous magnet
    velocity in the
        x direction
    :param np.ndarray Bz: magnetic field in the
    z direction

    :return: force in the y direction
    :rtype: float
    """
    Fy = np.sum(Q * vx * Bz)
    return Fy

def Fzfunc(Q, vx, By):
    """Force on the magnet in the z direction.

    :param np.ndarray Q: charge distribution
    :param float vx: instantaneous magnet
    velocity in the z direction
    x direction
    :param np.ndarray By: magnetic field in the
    y direction
    :return: force in the z direction
    :rtype: float
    """
    Fz = -np.sum(Q * vx * By)
    return Fz

Listing 1. Define the functions needed for Lorentz force law model calculating the forces on moving magnet from a charge distribution.

Graph and function mapping

The second step is to define the graph that contains all the function nodes and the edge flow in a DAG. The graph in mmodel is defined with the ModelGraph class. The class inherits from networkx.DiGraph of the popular graph library NetworkX[27]. All NetworkX operations can be used on mmodel graphs. The nodes and edges can be defined with all available NetworkX or mmodel syntax for adding nodes and edges. The edges represent the data flow, and the nodes represent the function. For the graph, the node names and edges are first defined using add_grouped_edge, then we map the functions to nodes using set_node_object. Listing 2 defines the graph G with grouped edges. The functions and output variable name are mapped to the nodes in the (node_name, function, output) tuple.

from mmodel import ModelGraph

G = ModelGraph(name="example_graph")
grouped_edges = [(["Bz", "Vx"], "Fy"), (["By", "Vx"], "Fz")]
G.add_grouped_edges_from(grouped_edges)
node_objects = [
    ("Bz", Bzfunc, "Bz"),
    ("By", Byfunc, "By"),
    ("Vx", Vxfunc, "vx"),
    ("Fy", Fyfunc, "Fy"),
    ("Fz", Fzfunc, "Fz"),
]
G.set_node_objects_from(node_objects)

Listing 2. Create a mmodel graph and map the functions to the corresponding graph nodes, and their output variable names.

Model and handler

The third step is to convert the graph into a model. The execution method is defined using the handler classes. The Model class takes graph and handler as input, and the resulting object is a Python callable, and its input arguments are automatically parsed. As of version 0.5, mmodel provides three handlers, BasicHandler, MemHandler, and H5Handler. The handler information is provided using the handler class, and additional keyword arguments to the handler class can be provided as keyword to the Model class.s The model can be defined as shown in Lst. 3. The graph of the model is accessible through the graph attribute.

from mmodel import Model, MemHandler

experiment = Model("experiment", G, handler=
    MemHandler)

Listing 3. Convert the mmodel graph to a model by defining the model name and execution method.

Metadata and graph representation

mmodel provides rich metadata and graph plotting capabilities. The model and graph metadata can be extracted by printing out the string value shown in Lst. 4. The graph representation uses the dot graph, a standard for representing the graph. With the Graphviz package,[28] the users can employ the default graph plotting method in mmodel or provide their own. Both graph and model have the draw method to display the metadata and the graph. The output of model.draw() is shown in Figure 7.

Figure 7. Experiment graph model generated by mmodel.

>>> print(G)
ModelGraph with 5 nodes and 4 edges

>>> print(experiment)
experiment(A, Ms, Q, f, grid, mu0, r, xm)
returns: (Fy, Fz)
graph: example_graph
handler: MemHandler

Listing 4. Print out mmodel graph and model metadata. The graph metadata shows the number of nodes and edges, and the model metadata shows the input, returns, execution method, and modifiers.

Model execution

Here we define representative experimental parameters and execute the model as a function, shown in Lst. 5. We choose the magnet to be a 250 nm radius cobalt sphere and define a sample grid size of dimension 2000 nm×2000 nm×500 nm2000\ \mathrm{nm} \times2000\ \mathrm{nm} \times500\ \mathrm{nm} in the shape of (25, 25, 25). The sample is centered at (0, 0, −600) nm, which makes the sample surface 100 nm away from the magnet surface. The instantaneous magnet position is (20, 0, 0) nm. The mock sample has a charge distribution of approximately 0.5 electron / nm³, and values are randomly generated. All the parameters defined are shown in Table II.

grid = np.ogrid[-1000:1000:25j, -1000:1000:25j,
    -350:-850:25j]  # nm
v_voxel = (2000/25)*(2000/25)*(500/25)  # nm^3
np.random.seed(0)
Q = np.random.rand(25, 25, 25) * 1.6e-19 *
    v_voxel  # A s
xm = 100  # nm
A = 300  # nm
f = 3000  # Hz
mu0 = 1.26e9  # aN/A^-2
Ms = 1.45e-3  # A/nm
r = 250  # nm
variablevalueunitdescription
AA300nmcantilever amplitude
ff3000Hzcantilever frequency
xmx_m100nmmagnet position
rr4000nmmagnet radius
μ0\mu_01.26×1091.26 \times10^{9}aN/A2^2vacuum permeability
MsM_s1.45×10−31.45 \times10^{-3}A/nmsaturation magnetization
QQ∼0.5\sim0.5 electron/nm3^3A·scharge distribution
gridgrid2000×2000×5002000 \times2000 \times500nmgrid points
voxelvoxel128000nm3^3grid voxel size

Table II (PDF p. 8). Input parameters for the Lorentz force law model, the units are adjusted to match the calculation.

# force in the unit of aN
Fy, Fz = experiment(A, Ms, Q, f, grid, mu0, r,
                    xm)

>>> print("{:.2f} aN".format(Fy), "{:.2f} aN".
format(Fz))
6.95 aN 0.15 aN

Listing 5. Define input parameters and execute experiment model. The resulting forces are in the unit of aN.

>>> print(experiment_debug)
experiment_debug(A, Ms, Q, f, grid, mu0, r, xm)
returns: (Fy, Fz, vx)
graph: example_graph
handler: MemHandler

Listing 6. Create a model with customized returns and returns order by define the returns parameter.

Graph execution returns

The model class allows the user to define the return parameters and the return order. For example, to investigate the intermediate value vxv_x along with the forces, we simply add vxv_x to the experiment definition, as shown in Lst. 6.

experiment_debug = Model(
    name="experiment_debug", graph=G, handler=
    MemHandler, returns=["Fy", "Fz", "vx"]

Modifier

The modifier is one of the core features of mmodel. The modifiers do not change the original function definition. Instead, they are Python wrappers that modify the functions after their definition.

For example, the modifier that prints out the node value can be defined as Lst. 7. The pattern argument specifies the format of the output. The modifier adds a printing step after the node calculation.

from functools import wraps

def print_result(pattern, end="\n"):
    """Print out function return values.

    :param str pattern: print format
    :param str end: print at the end of the
    string.
    """

    def stdout_modifier(func):
        @wraps(func)
        def wrapped(**kwargs):
            result = func(**kwargs)
            print(pattern.format(result), end=
end)
            return result

        return wrapped
    stdout_modifier.metadata = f"print_result({
repr(pattern)}, {repr(end)})"
    return stdout_modifier

Listing 7. Define the modifier that prints out the formatted return value of the function after execution.

The modifier can decorate any Python function, adding additional steps before or after the execution. The modifiers can be added to the node or model in a list with their keyword parameters in dictionary form, and multiple modifiers can be applied. Listing 8 adds the modifier to the Vx node and the experiment model, which adds the print steps of formatted VxV_x, FyF_y, and FzF_z values and their units.

# at the node level
G.set_node_object(
    node="Vx",
    func=Vxfunc,
    output="vx",
    modifiers=[print_result("vx: {:.2e} nm/s", "
    | ")],

# at the model level
experiment = Model(
    "experiment",
    graph=G,
    handler=MemHandler,
    modifiers=[print_result("Fy: {0[0]:.2f} aN |
    Fz: {0[1]:.2f} aN")],
)

>>> Fy, Fz = experiment(A, Ms, Q, f, grid, mu0,
r, xm)
vx: 5.33e+06 nm/s | Fy: 6.95 aN | Fz: 0.15 aN

Listing 8. Apply the print_result modifier during the function node and model definition.

Create loops within the model

In this section, we define a function that can modify the graph of a model and create a loop inside the graph. We can define a shortcut combining the proper steps of creating the loop discussed in Section II C. The resulting shortcut function, shown in Lst. 9, allows the model to take list values of the target parameter. mmodel does not provide the shortcut function for looping since many loop operations can be package specific.

from mmodel.modifier import loop_input


def loop_shortcut(model: Model, loop_param: str,
                  submodel_name: str):
    """Shortcut to create loops of loop_param in
    the model.

    :param mmodel.Model model: the model to be
    looped
    :param str loop_param: the loop parameter
    :param str submodel_name: the name of the
    submodel

    :return: the looped model
    :rtype: mmodel.Model
    """

    G = model.graph
    # determine the subgraph that has the loop
    # parameter as the input
    H = G.subgraph(inputs=[loop_param])
    H.name = f"{submodel_name}_subgraph"

    # create the inner function and substitute
    # the subgraph with the loop-modifier
    loop_func = Model(submodel_name, H, model.
    handler)

    # determine the subgraph returns
    output = "({})".format(", ".join(H.returns))

    # replace the subgraph, and add the
    # loop_modifier
    loop_graph = G.replace_subgraph(
        H,
        f"{loop_param} loop node",
        loop_func,
        output=output,
        modifiers=[loop_input(loop_param)],
    )
    loop_graph.name = f"{loop_param}_loop_{G.
    name}"
    model_name = f"{loop_param}_loop_{model.name
    }"
    return Model(model_name, loop_graph, model.
    handler)

Listing 9. Define the shortcut that loops a given parameter within a model. The shortcut modifies the graph and the subnodes.

The shortcut can be used directly on an existing model, as shown in Lst. 10. The resulting model requires the ff input to be iterable, and the results are the iterated (Fy,Fz)(F_y,F_z) pairs. The graph is modified to show the proper units of the force nodes. The resulting model graph and the loop subgraph are shown in Figure 8.

Figure 8. Model graph that loops parameter ff generated using the loop_shortcut. Top: graph of the modified model. Bottom: the graph of the ff loop node.

# Modify the Fy and Fz nodes to output the
# result.
G.modify_node("Fy", modifiers=[print_result("Fy:
    {:.2f} aN", " | ")], inplace=True)
G.modify_node("Fz", modifiers=[print_result("Fz:
    {:.2f} aN")], inplace=True)
experiment = Model("experiment", G, MemHandler)
# define the loop experiment
>>> loop_experiment = loop_shortcut(experiment,
    loop_param = "f")
>>> print(loop_experiment)
f_loop_experiment(A, Ms, Q, f, grid, mu0, r, xm)
returns: (Fy, Fz)
graph: f_loop_example_graph
handler: MemHandler

# define frequencies to loop over and execute
    the experiment
>>> f = np.arange(3000, 8000, 1000) # Hz
>>> loop_result = loop_experiment(A, Ms, Q, f,
    grid, mu0, r, xm)
vx: 5.33e+06 nm/s | Fy: 6.95 aN | Fz: 0.15 aN
vx: 7.11e+06 nm/s | Fy: 9.26 aN | Fz: 0.20 aN
vx: 8.89e+06 nm/s | Fy: 11.58 aN | Fz: 0.25 aN
vx: 1.07e+07 nm/s | Fy: 13.89 aN | Fz: 0.30 aN
vx: 1.24e+07 nm/s | Fy: 16.21 aN | Fz: 0.35 aN

Listing 10. Create a model that loops parameter ff based on the Lorentz force model and execute the model with the iterated ff value.

Please check out the detailed documentation at https://marohn-group.github.io/mmodel-docs/.

References

  1. [1]D. T. Snyder, C. J. Pulliam, Z. Ouyang, and R. G. Cooks, “Miniature and Fieldable Mass Spectrometers: Recent Advances,” Anal. Chem. 88, 2–29 (2016).DOI
  2. [2]D. Nolting, R. Malek, and A. Makarov, “Ion traps in modern mass spectrometry,” Mass Spec Rev 38, 150–168 (2019).
  3. [3]C. Fadley, “X-ray photoelectron spectroscopy: Progress and perspectives,” J. Electron Spectrosc. Relat. Phenom. 178–179, 2–32 (2010).DOI
  4. [4]E. Gann, A. T. Young, B. A. Collins, H. Yan, J. Nasiatka, H. A. Padmore, H. Ade, A. Hexemer, and C. Wang, “Soft x-ray scattering facility at the Advanced Light Source with real-time data processing and analysis,” Rev. Sci. Instrum. 83, 045110 (2012).DOI
  5. [5]P. Norman and A. Dreuw, “Simulating X-ray Spectroscopies and Calculating Core-Excited States of Molecules,” Chem. Rev. 118, 7208–7248 (2018).DOI
  6. [6]D. Rugar, R. Budakian, H. J. Mamin, and B. W. Chui, “Single spin detection by magnetic resonance force microscopy,” Nature 430, 329–332 (2004).
  7. [7]C. L. Degen, M. Poggio, H. J. Mamin, C. T. Rettner, and D. Rugar, “Nanoscale magnetic resonance imaging,” Proc. Natl. Acad. Sci. U.S.A. 106, 1313–1317 (2009).DOI
  8. [8]E. W. Moore, S. Lee, S. A. Hickman, S. J. Wright, L. E. Harrell, P. P. Borbat, J. H. Freed, and J. A. Marohn, “Scanned-probe detection of electron spin resonance from a nitroxide spin probe,” Proc. Natl. Acad. Sci. U.S.A. 106, 22251–22256 (2009).DOI
  9. [9]A. Vinante, G. Wijts, O. Usenko, L. Schinkelshoek, and T. Oosterkamp, “Magnetic resonance force microscopy of paramagnetic electron spins at millikelvin temperatures,” Nat Commun 2, 572 (2011).DOI
  10. [10]J. M. Nichol, E. R. Hemesath, L. J. Lauhon, and R. Budakian, “Nanomechanical detection of nuclear magnetic resonance using a silicon nanowire oscillator,” Phys. Rev. B 85, 054414 (2012).DOI
  11. [11]A. Trisovic, M. K. Lau, T. Pasquier, and M. Crosas, “A large-scale study on research code quality and execution,” Sci Data 9, 60 (2022).DOI
  12. [12]J. F. Pimentel, L. Murta, V. Braganholo, and J. Freire, “A Large-Scale Study About Quality and Reproducibility of Jupyter Notebooks,” in 2019 IEEE/ACM 16th International Conference on Mining Software Repositories (MSR) (IEEE, Montreal, QC, Canada, 2019) pp. 507–517.DOI
  13. [13]D. V. M. Bishop, “Facilibility in Science: Responding to Errors in the Work of Oneself and Others,” Adv. Meth. Pract. Psychol. Sci. 1, 432–438 (2018).
  14. [14]J. M. Perkel, “How to fix your scientific coding errors,” Nature 602, 172–173 (2022).DOI
  15. [15]J. F. Strand, “Error tight: Exercises for lab groups to prevent research mistakes.” Psychological Methods (2023), 10.1037/met0000547.DOI
  16. [16]E. Deelman, D. Gannon, M. Shields, and I. Taylor, “Workflows and e-Science: An overview of workflow system features and capabilities,” Future Gener Comput Syst 25, 528–540 (2009).DOI
  17. [17]C. S. Liew, M. P. Atkinson, M. Galea, T. F. Ang, P. Martin, and J. I. V. Hemert, “Scientific Workflows: Moving Across Paradigms,” ACM Comput. Surv. 49, 1–39 (2017).DOI
  18. [18]D. J. Griffiths, Introduction to Electrodynamics, 4th ed. (Pearson, Boston, 2013).
  19. [19]O. D. Jefimenko, “Force exerted on a stationary charge by a moving electric current or by a moving magnet,” Am. J. Phys. 61, 218–222 (1993).
  20. [20]E. Deelman, K. Vahi, M. Rynge, R. Mayani, R. F. da Silva, G. Papadimitriou, and M. Livny, “The Evolution of the Pegasus Workflow Management Software,” Comput. Sci. Eng. 21, 22–36 (2019).DOI
  21. [21]B. Ludäscher, I. Altintas, C. Berkley, D. Higgins, E. Jaeger, M. Jones, E. A. Lee, J. Tao, and Y. Zhao, “Scientific workflow management and the Kepler system,” Concurrency Computat.: Pract. Exper. 18, 1039–1065 (2006).DOI
  22. [22]T. McPhillips, S. Bowers, D. Zinn, and B. Ludäscher, “Scientific workflow design for mere mortals,” Future Gener. Comput. Syst 25, 541–551 (2009).
  23. [23]S. P. Huber, S. Zoupanos, M. Uhrin, L. Talirz, L. Kahle, R. Häuselmann, D. Gresch, T. Müller, A. V. Yakutovich, C. W. Andersen, F. F. Ramirez, C. S. Adorf, F. Gagliulo, S. Kumbhar, E. Passaro, C. Johnston, A. Merkys, A. Cepellotti, N. Mounet, N. Marzari, B. Kozinsky, and G. Pizzi, “AiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance,” Sci Data 7, 300 (2020).
  24. [24]M. Rocklin, “Dask: Parallel Computation with Blocked algorithms and Task Scheduling,” in Python in Science Conference (Austin, Texas, 2015) pp. 126–132.DOI
  25. [25]M. Jarecka, M. Goncalves, C. Markiewicz, O. Esteban, N. Lo, J. Kaczmarzyk, and S. Ghosh, “Pydra – a flexible and lightweight dataflow engine for scientific analyses,” in Python in Science Conference (Austin, Texas, 2020) pp. 132–139.DOI
  26. [26]C. R. Harris, K. J. Millman, S. J. van der Walt, R. Gommers, P. Virtanen, D. Cournapeau, E. Wieser, J. Taylor, S. Berg, N. J. Smith, R. Kern, M. Picus, S. Hoyer, M. H. van Kerkwijk, M. Brett, A. Haldane, J. F. del Río, M. Wiebe, P. Peterson, P. Gérard-Marchant, K. Sheppard, T. Reddy, W. Weckesser, H. Abbasi, C. Gohlke, and T. E. Oliphant, “Array programming with NumPy,” Nature 585, 357–362 (2020).
  27. [27]A. A. Hagberg, D. A. Schult, and P. J. Swart, “Exploring network structure, dynamics, and function using NetworkX,” in Proceedings of the 7th Python in Science Conference, edited by G. Varoquaux, T. Vaught, and J. Millman (Pasadena, CA USA, 2008) pp. 11–15.
  28. [28]E. R. Gansner and S. C. North, “An open graph visualization system and its applications to software engineering,” Software: Practice and Experience 30, 1203–1233 (2000).doi.org/10.1002/1097-024x(200009)30:11<1203::aid-spe338>3.0.co;2-n

Paper details

vlnc:W_sf8sys59
Version
v1 · latest
Published
Fresh — added to the Hub within the last 30 days
Added
License
CC BY 4.0
Usage

views · 0

downloads · 0

A view counts once per browser per day, a download each time the PDF is requested.

  • Physics and Astronomy

Not recorded for this paper

View statement
Looking for related papers…
Contents