\graphicspath{ {./images/} }
In this section we present ModFossa, a fast and easy-to-use Python library for creating and
simulating ion channel kinetics using continuous time Markov processes. A
brief discussion of ModFossa's features, components, are provided here.  For
more details regarding the design of ModFossa the reader is referred to \cite{garreth-thesis} and for the source
code the reader is referred to \cite{garreth-source}.

For those interested, the name ModFossa was formed from two Latin words ---
mod, and fossa, which can be interpreted as \emph{open channel} when written
together.

Before we begin the design overview,
Table \ref{table:simulators} compares the basic features of each simulator,
including our solution, ModFossa.

\begin{table*}
\scriptsize
\begin{center}
  \caption{Feature comparison of several ion channel simulators which use
Markov models.}
  \label{table:simulators}
  \begin{tabular}{ | p{2.2cm} | p{0.8cm} |p{0.4cm} |p{1.2cm} |p{1.2cm} |p{0.8cm}
|p{1.8cm} |p{0.6cm} |p{1.5cm} |} \hline
    Name & Model & GUI & Scriptable & Plotting & Plot \mbox{format} & Simulation
type & OS & License \\ \hline
    IonChannelLab\cite{castillo-2010} & Markov & yes & no & yes, \mbox{interactive} & bitmap &
    numerical integration, Monte Carlo, Q-Matrix & Win. & Free, no source
    available \\ \hline
    ChannelLab\cite{channellab} & Markov & yes & no & yes & bitmap & numerical
    integration, Monte Carlo & Win. & Proprietary \\ \hline
    QUB & HMM & yes & yes & yes, \mbox{interactive} & bitmap & numerical \mbox{integration} & Win.,
    Mac, Linux & GPL \\ \hline
    ModFossa & Markov & no & yes, from Python & yes & vector & numerical
    \mbox{integration} & Linux & GPL \\ \hline
  \end{tabular}
\end{center}
\end{table*}



\subsection{Features}
{\bf Python interface:}
ModFossa provides easy, yet versatile and powerful ion channel modeling through
its novel Python interface. Python is well-used in the scientific and academic
community; however, we are unaware of any Python libraries which facilitate
the creation and simulation of ion channel kinetics. The popularity of Python
as a research tool stems from its simple syntax and extensive standard library,
and the availability of many high-quality open source numeric and scientific
libraries. Additional qualities of Python include easy third party library
installation; strong, dynamic typing; and an interactive interpreter.

ModFossa can also be used directly as a C++ library, allowing for more
flexibility.

{\bf Easy model creation:}
ModFossa allows the user to define an ion channel's Markov model using states,
rates, and connections. States and rates are referred to by their user-supplied
names. This allows the user to create the model in any order. For example,
connections can be defined before the definition of the states and rate
constants.

{\bf States:} States represent the various channel states as defined
by a continuous time Markov chain. All states are referred to by unique name
which is assigned by the user during
creation. States are created as either non-conducting or conducting.
Additionally, the gating of conducting states can by specified during
construction. The gating parameter is used to simulate states that are
partially conducting. For example, assigning a gating value of 0.5 to a state in
a particular model may be used to simulate channel blocking by 50 percent.

{\bf Rates:} 
Rates represent the kinetic rate constants which define the rate
of transition between two states. Rates are referred to by unique name. ModFossa
includes the following rate constant types: constant, Boltzmann voltage
dependence, exponential voltage dependence, and ligand-gated. The equations
for each rate constant are presented below.

\emph{Constant} rate constant are defined by a single parameter, $k$, like so:
\begin{equation}
 rate = k.
\end{equation}

\emph{Exponential} voltage dependent rate constants depend exponentially on
the membrane voltage: 
\begin{equation}
 rate(V) = a * exp(k*V),
\end{equation}
where $V$ is the membrane voltage, $exp$ is the exponential function, and $a$
and $k$ are parameters. 

% Right slash in math mode for fractions.
\newcommand{\slfrac}[2]{\left.#1\middle/#2\right.}

\emph{Boltzmann} voltage dependence is defined using the sigmoid-like
Boltzmann equation:
\begin{equation}
 rate(V) = \frac{a}{\slfrac{1+exp[(V-V_{0.5})}{k}]},
\end{equation}
where $V$ is the membrane voltage, $V_{0.5}$ is the half-maximal activation
voltage (given as a parameter), $exp$ is the exponential function, and $a$
and $k$ are parameters. Taken from Angermann et al. \cite{angermann-2006}.  

\emph{Ligand-gated} rate constants depend on the concentration of a particular
ionic species, $S$, like so:
\begin{equation}
 rate([S]) = k * [S] ^ {n}, 
\end{equation}
where $[S]$ is the concentration of ligand $S$, $n$ is the ligand power, and
$k$ is a parameter.


{\bf Connections:} Connections define a transition from one unique
state to another using a specified rate constant. States can have multiple
ingoing and outgoing connections. Rate constants may also be used in multiple
connections.
 
{\bf Experiment definition:}
An experiment consists of a channel Markov model, a voltage protocol, and an
optional concentration protocol. 

{\bf Voltage protocol:}
Voltage protocols are a fundamental technique in electrophysiology used to
measure the current response of ion channels. In the laboratory, a small
electrode is inserted into the cell, through the cell membrane. The electrode,
and therefore the cell membrane, is held constant at a desired voltage for a
length of time, as defined by the voltage protocol. A typical voltage protocol
is shown in Figure \ref{fig:voltage_protocol}. As shown in the figure, the
voltage protocol begins with a \emph{hold stage} at -50 mV for 100 ms. Next, a
1 second long \emph{stepped stage} is defined, which steps the voltage from
-100 mV to 140 mV in 20 mV increments. The voltage protocol ends with another
hold stage at -80 mV.

The voltage protocol shown in Figure \ref{fig:voltage_protocol} is easily
defined in ModFossa by adding two hold stages, and one stepped stage. A
ModFossa voltage protocol can have any number of hold stages, but only one
stepped stage.  

%%%% Voltage protocol %%%%
\begin{figure}[h]
\begin{center}
 
\includegraphics[width=3.0in]
{angermann_ca_voltage_protocol.eps}
    \caption{Example of a voltage protocol plot generated using ModFossa. This
protocol starts with a hold stage at -50 mV for 100 ms. Next, a
1 second long \emph{stepped stage} is defined, which steps the voltage from
-100 mV to 140 mV in 20 mV increments. The voltage protocol ends with another
hold stage at -80 mV. }
    \label{fig:voltage_protocol}
\end{center}
\end{figure}



{\bf Concentration protocol:}
A concentration protocol defines the concentration values (extracellular
or intracellular) of a certain ligand. Like a voltage protocol, ModFossa's
concentration protocols are defined using \emph{hold stages}. However, there is
no support for stepped concentration protocol stages. During simulation, the
simulator will run the model through the entire voltage protocol using a single
stage from the concentration protocol. Next, the concentration protocol will
advance to the next stage, and the voltage protocol will be run using the new
concentration value. This continues until there are no stages left in the
concentration protocol.


{\bf Data analysis and plotting:}   
ModFossa supports the creation of a number of useful plots using the Python
plotting library, PyPlot. Unlike other simulators, the
plots can be saved easily in a vector graphics format. Visual examples of each
plot type are found in Section 4.

% \subsubsection{state probabilities}
% The state probabilities plot shows the evolution of the occupancy of each state
% in the Markov model over time.
%    
% \subsubsection{IV curve}
% IV curves show the ion channel's current as a function of membrane voltage. The
% voltages used to generate the IV curve are taken from the \emph{stepped stage}
% of the voltage protocol.
% 
% \subsubsection{conductance versus concentration}
% 
% \subsubsection{conductance versus voltage}
 

 
{\bf Model and experiment validation:}
To assist the user in creating a valid simulation, ModFossa
provides validation methods which return detailed messages regarding any
problems with the model and experiment definitions. Specific error conditions
include: \emph{no connections defined}, \emph{max conductance not defined},
\emph{rate constant not defined}, \emph{state not defined}, \emph{ligand not
defined}, \emph{no voltage protocols defined}, and \emph{no experiment sweeps
defined}.


\subsection{Implementation}

{\bf Development tools:}
C++ code was developed under Ubuntu Linux using Eclipse CDT. CMake was chosen as
the build system. Unit tests for the C++ code were written using the Google Test
framework. Having unit tests available aided the development process by
instilling confidence in the correctness of the code, especially during
refactoring. Google Test is included in the source tree, and is built by CMake
during the build process. This removes the need for the user to have Google Test
installed on the target computer.

Doxygen was used to generate documentation for the C++ code, while the Python
documentation was generated using Sphinx. Generated documentation can be found
in the Appendix. 

{\bf Dependencies:}
Sundials (SUite of Nonlinear and DIfferential/ALgebraic equation Solvers) is a C
library developed by Lawrence Livermore National Laboratory. ModFossa uses
Sundials to solve the system of ordinary differential equations governing the
ion channel state probabilities. Armadillo, a C++ linear algebra library
provides easy-to-use matrix structures and linear solvers, and is also used by
ModFossa. However, it would be ideal to remove the dependency on Armadillo in
order to remove complications during ModFossa’s installation.

In order to run ModFossa's Python interface, two Python libraries are required:
MatplotLib and Numpy. 


