#LyX 2.1 created this file. For more info see http://www.lyx.org/
\lyxformat 474
\begin_document
\begin_header
\textclass article
\use_default_options true
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman palatino
\font_sans helvet
\font_typewriter cmtt
\font_math auto
\font_default_family sfdefault
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize 11
\spacing single
\use_hyperref true
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks true
\pdf_backref false
\pdf_pdfusetitle true
\pdf_quoted_options "linkcolor=blue, urlcolor=blue"
\papersize letterpaper
\use_geometry true
\use_package amsmath 1
\use_package amssymb 1
\use_package cancel 1
\use_package esint 1
\use_package mathdots 1
\use_package mathtools 1
\use_package mhchem 1
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\justification true
\use_refstyle 1
\boxbgcolor #e4fbff
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 3cm
\topmargin 3cm
\rightmargin 3cm
\bottommargin 3cm
\headheight 1cm
\headsep 1cm
\footskip 1cm
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip bigskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle fancy
\bullet 0 0 30 -1
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title

\series bold
BETSE 0.2
\end_layout

\begin_layout Standard
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/betse_logo_2.png
	lyxscale 40
	width 80text%

\end_inset


\end_layout

\begin_layout Standard
\noindent
\align center

\series bold
\size largest
B
\series default
io
\series bold
E
\series default
lectric 
\series bold
T
\series default
issue 
\series bold
S
\series default
imulation 
\series bold
E
\series default
ngine
\end_layout

\begin_layout Standard
\align center
Command Line Interface Documentation (Version 0.2) 
\end_layout

\begin_layout Standard
\noindent
\align center
Alexis Pietak
\end_layout

\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset


\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset


\end_layout

\begin_layout Section
Preamble
\begin_inset CommandInset label
LatexCommand label
name "sec:Preamble"

\end_inset


\end_layout

\begin_layout Standard
This 
\series bold
B
\series default
io
\series bold
E
\series default
lectric 
\series bold
T
\series default
issue 
\series bold
S
\series default
imulation 
\series bold
E
\series default
ngine (BETSE) has been created to facilitate bio-realistic modeling of dynamic
 electrochemical phenomena in gap junction networked cell collectives.
 
\end_layout

\begin_layout Standard
BETSE is intended to help test hypotheses relating to experimentally accessible
 electrochemical phenomena important in morphogenesis, regeneration, and
 disease processes such as cancer.
 A special emphasis is placed on how electrochemical phenomena can lead
 to spatio-temporal pattern formation.
 
\end_layout

\begin_layout Standard
Real-world parameter values have been used wherever possible, with the intention
 of creating bio-realistic output that can directly compliment experimental
 results.
\end_layout

\begin_layout Standard
This early version (0.2) of BETSE embodies only the very core aspects of
 the simulation engine and is intended for check-in purposes only.
 
\end_layout

\begin_layout Standard
In addition to this written documentation, a set of video tutorials (BETSE_Tutor
ial_*.mp4) have been created to help you get up and running with BETSE on
 your system.
\end_layout

\begin_layout Section
Getting Started 
\begin_inset CommandInset label
LatexCommand label
name "sec:System-Requirements"

\end_inset


\end_layout

\begin_layout Subsection
Installation
\end_layout

\begin_layout Standard
BETSE does not need to be formally installed on a computer as the executable
 embeds a fully-working, operating-system-specific Python environment with
 all required dependencies.
 
\end_layout

\begin_layout Standard
To run BETSE, we recommend that you make a new directory on your computer
 and put the BETSE executable (specific to the operating system) into that
 new directory.
 This version of BETSE is a command-line-interface (CLI) program, meaning
 it is run by issuing written commands at the computer's Terminal.
 Unfortunately, due to the early stage of development, there is currently
 no graphical user interface (GUI) to assist you.
 Section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Basic-Workflow-and"

\end_inset

 outlines the basic steps and commands that you will use to run simulations
 in BETSE.
 
\end_layout

\begin_layout Standard
If you're having trouble understanding the basic work-flow, please watch
 the video tutorials BETSE_Tutorial_1.mp4 to BETSE_Tutorial_4.mp4.
\end_layout

\begin_layout Subsection
System Requirements
\end_layout

\begin_layout Standard
Supported operating systems: 
\end_layout

\begin_layout Itemize
Mac OS X 10.6 (Snow Leopard) or newer.
 
\end_layout

\begin_layout Itemize
Linux distributions providing at least 
\emph on
glibc
\emph default
 2.19 or newer.
 This includes, but is not limited to, the following Linux distributions:
 Linux Mint 17.1 (Rebecca) or newer.
 Ubuntu 14.10 (Utopic Unicorn) or newer.
 BETSE currently runs only on 64-bit systems of Linux.
 This is principally due to the increasing obsolescence of 32-bit systems,
 particularly for scientific work.
\end_layout

\begin_layout Standard
Future versions of BETSE will support:
\end_layout

\begin_layout Itemize
Microsoft Windows XP or newer
\end_layout

\begin_layout Standard
However, Windows is not available at this time.
 
\end_layout

\begin_layout Standard
BETSE is memory intensive.
 We currently recommend your system have at least 4 GB RAM for BETSE simulations.
 An ideal system for simulation would have 16 GB of RAM.
 
\end_layout

\begin_layout Subsection
Memory Demands
\end_layout

\begin_layout Standard
BETSE uses so-called 'direct' (i.e.
 matrix-based) solvers in order to make each iteration step of an initialization
 or simulation run as quick as possible.
 The disadvantage of 'direct' solvers is that the matrices can be large
 and are stored on disk or active in memory (RAM).
 Therefore, BETSE sims can be surprisingly memory intensive, especially
 for simulations that include a full environment and extracellular spaces
 around each cell.
 Tables 
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Disk-space-used"

\end_inset

 and 
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Maxium-RAM-used"

\end_inset

 summarize the disk and RAM memory used to create a cell cluster of various
 sizes and will hopefully help you find the maximum sized cluster that your
 system can handle.
 
\end_layout

\begin_layout Standard

\series bold
\begin_inset Float table
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="3" columns="5">
<features rotate="0" tabularvalignment="middle" tabularwidth="100text%">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
Simulation Type
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
200x200 um
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
400x400 um
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
600x600 um
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
800x800 um
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
simulate ECM = True
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
61.6 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
443 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
1900 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
7000 Mb
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
simulate ECM = False
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
15.5 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
146 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
694 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
2400 Mb
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Plain Layout

\series bold
\begin_inset Caption Standard

\begin_layout Plain Layout
Disk space used for basic cell cluster creation for various world sizes
 and for full environmental simulation (simulate ECM = True) and basic simulatio
n with homogeneous environment (simulate ECM = False).
\begin_inset CommandInset label
LatexCommand label
name "tab:Disk-space-used"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard

\series bold
\begin_inset Float table
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="3" columns="5">
<features rotate="0" tabularvalignment="middle" tabularwidth="100text%">
<column alignment="center" valignment="top" width="0pt">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top" width="0pt">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
Simulation Type
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
200x200 um
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
400x400 um
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
600x600 um
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout

\series bold
800x800 um
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
simulate ECM = True
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
124 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
886 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
3800 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
14000 Mb
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
simulate ECM = False
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
61 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
300 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
1388 Mb
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
4800 Mb
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Plain Layout

\series bold
\begin_inset Caption Standard

\begin_layout Plain Layout
Maximum RAM used for basic cell cluster creation for various world sizes
 and for full environmental simulation (simulate ECM = True) and basic simulatio
n with homogeneous environment (simulate ECM = False).
\begin_inset CommandInset label
LatexCommand label
name "tab:Maxium-RAM-used"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Known Issues
\end_layout

\begin_layout Standard
While the Mac OS X executable of BETSE was intended to be 64-bit, it was
 recently discovered to be only 32-bit.
 This problem will be solved in future releases of BETSE.
 BETSE will still run on 64-bit versions of Mac OS X, however, the maximum
 RAM for a simulation will be limited to 4 Gb.
 It's therefore recommended that your world sizes not exceed 500x500 um
 and that grid sizes not exceed 50 x 50.
\end_layout

\begin_layout Standard
There are no known issues for Linux based systems, where only a 64-bit version
 is available, and the maximum RAM for a simulation is restricted only by
 your hardware.
 
\end_layout

\begin_layout Section
What's New in BETSE 0.2?
\end_layout

\begin_layout Subsection
Major New Features
\end_layout

\begin_layout Standard
BETSE 0.2 includes the four major new features:
\end_layout

\begin_layout Enumerate
Optional use of bitmap images (*.png) to control cell cluster shape and to
 define tissue profiles within the cluster (Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Bitmap-images"

\end_inset

).
 
\end_layout

\begin_layout Enumerate
Ability to define tissue profiles as spatial regions within the cluster
 having optional unique base membrane properties, isolated network connectivity,
 and dynamic elements such as gated ion channels.
 
\end_layout

\begin_layout Enumerate
Optional ability to simulate the extracellular spaces and environment surroundin
g the cell culture, with calculation of variables including: voltage, electric
 fields, currents, and electroosmotic flow.
 
\end_layout

\begin_layout Enumerate
Upgraded model to full Finite Volume Method solver for increased accuracy
 and stability.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/bitmap_control_tissue_profiles.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Bitmap images (top row) can now be used to control overall shape of the
 cell cluster (clipping) as well as to cut a hole into the model upon initializa
tion (cavity), to define cuts for the model at the onset of a simulation
 (cuts), and to define tissue profiles (nerves, spot, wound) where different
 scheduled interventions and dynamic channels may be assigned.
 
\begin_inset CommandInset label
LatexCommand label
name "fig:Bitmap-images"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Minor New Features
\end_layout

\begin_layout Standard
BETSE 0.2 also includes a range of other new features:
\end_layout

\begin_layout Enumerate
Streamline/vector plots and animations of ionic currents, electric fields,
 and fluid flow.
 
\end_layout

\begin_layout Enumerate
Spatial functions applied to membrane permeability simulate x,y or radial
 V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 gradients in space and time.
 
\end_layout

\begin_layout Enumerate
Electroosmotic flow, pressure and force are calculated.
 
\end_layout

\begin_layout Enumerate
Lateral movement of ion pumps and channels in the plasma membrane under
 the action of tangential electric fields and electroosmotic flow.
 
\end_layout

\begin_layout Enumerate
Option to apply an external voltage to the global boundaries of the simulation
 for a scheduled period of time.
 
\end_layout

\begin_layout Enumerate
Optionally include a chemical substance with user-specified initial concentratio
n in cells and environment, membrane and environmental diffusion constants,
 charge state, and ion channel target with control over gating characteristics.
 This can be used as a gating ligand similar to a neurotransmitter.
 
\end_layout

\begin_layout Enumerate
Cluster boundary detection algorithms working with both concave and convex
 geometries, and allow for optional creation of an environmental boundary
 with tight-junctions.
 The tight junctions can additionally have variable permeability to individual
 ions of the simulation.
 
\end_layout

\begin_layout Subsection
New Workflow
\end_layout

\begin_layout Standard
BETSE 0.2 features a new workflow:
\end_layout

\begin_layout Enumerate

\series bold
Create your geometries:
\series default
 First, decide on your cluster shape and the geometric properties of tissue
 profiles and any amputated regions, working these up in a graphics program
 such as Gimp or Inkscape.
 The images being used for a single model should all be square bitmaps,
 recommended 500x500 pixels per side, *.png file format, and all contained
 in the same directory one level down from your configuration file.
 When creating a default configuration file using the command 'betse config
 ~/path_to_config/config_filename.yaml' a default yaml configuration file
 will be created and a directory called 'geo' will be copied to the path.
 The directory 'geo' contains the sub-directories: 'circle', 'ellipse' and
 'planaria', each of which have example bitmap image sets that can be used
 to define models with various tissue profiles.
 See section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Using-Bitmaps-to"

\end_inset

 for details.
 
\end_layout

\begin_layout Enumerate

\series bold
Set up your model: 
\series default
Next, decide on the specifics of what you're going to model.
 At the command line, you may wish to create a default configuration file
 using the command 'betse config ~/path_to_config/config_filename.yaml'.
 Open, edit, and save the generated config_filename.yaml in a text editor
 of your choice.
 Much of this documentation deals with what configuration file settings
 achieve specific goals.
 
\end_layout

\begin_layout Enumerate

\series bold
Seed your cell cluster: 
\series default
Next, use the configuration file to create a cell cluster using the command
 'betse seed ~/path_to_config/config_filename.yaml'.
 This will create a world file on your hard drive (with directory and filename
 specified in the config file settings, see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Defining-Save/Load-Paths"

\end_inset

).
 
\end_layout

\begin_layout Enumerate

\series bold
Init your cluster:
\series default
 Next, use the config file to perform an initialization (otherwise called
 an 'init') on the cell cluster and environment, which helps ensure the
 system is at or near a steady state.
 To do this use the command: 'betse init ~/path_to_config/config_filename.yaml'.
\end_layout

\begin_layout Enumerate

\series bold
Sim your simulation:
\series default
 After seeding your world and initializing, perform the actual simulation
 with all desired scheduled interventions and dynamic channels.
 To do this use the command: 'betse sim ~/path_to_config/config_filename.yaml'.
\end_layout

\begin_layout Enumerate

\series bold
Plot data: 
\series default
At any point after seeding, initializing and/or simulating, data generated
 during seed, init and sim can be plotted using settings from the configuration
 file used.
 Settings in the 
\emph on
Results
\emph default
 portion of the config file (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Results-Output-and"

\end_inset

) can be edited to create different kinds of plotted data, and to give the
 plots a different appearance.
 
\end_layout

\begin_layout Section
Basic Commands
\begin_inset CommandInset label
LatexCommand label
name "sec:Basic-Workflow-and"

\end_inset


\end_layout

\begin_layout Subsection
Your First Simulation
\end_layout

\begin_layout Standard
This first version of BETSE is a command-line-interface (CLI) program, meaning
 it is run by issuing written commands at the Terminal as there is currently
 no graphical user interface (GUI).
 
\end_layout

\begin_layout Standard
To help us all cope with the absence of a GUI, program settings are specified
 by a 
\emph on
configuration file
\emph default
, which is essentially a special kind of text file that you can edit with
 a program such as 
\emph on
Gedit
\emph default
 (Linux), 
\emph on
Textwrangler
\emph default
 (Mac), or 
\emph on
Notepad
\emph default
 (Windows).
 We will get into thorough descriptions of the config file settings in subsequen
t sections of this documentation, but for now let's go through some CLI
 basics.
 
\end_layout

\begin_layout Standard
To get to the Terminal (command line) on 
\series bold
Mac
\series default
: open 
\emph on
Finder
\emph default
, select 
\emph on
Applications
\emph default
, choose 
\emph on
Utilities
\emph default
 and double click on 
\emph on
Terminal
\emph default
.
 On 
\series bold
Linux
\series default
, simply open the 
\emph on
Menu
\emph default
, select 
\emph on
Accessories
\emph default
, and choose the 
\emph on
Terminal
\emph default
.
 
\end_layout

\begin_layout Standard
Once in the terminal, change the directory to the one holding the BETSE
 executable specific to your system.
 For example, if you placed the executable into your 'Home' directory under
 an 'Applications' folder and inside a 'BETSE' folder you'd type:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
> cd ~/Applications/BETSE
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To see if the program works at all, once you've changed the directory, run
 BETSE from that directory by typing:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A help message should appear, which goes over the top-level commands for
 BETSE.
 
\end_layout

\begin_layout Standard
In order to test that the program works on your system and get a hassle-free
 look at how things will work, while still in the directory that holds the
 BETSE executable next type:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse try
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This 'try' command does everything necessary to run default initialization
 and simulation runs, and saves the visualized results on your computer
 in a new folder called 'sample_sim', appearing wherever you have copied
 and run the BETSE executable.
 
\end_layout

\begin_layout Standard
Once the initializations and simulations are running, you should see a continuou
sly updating figure appear, which is plotting the V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 for the cell collective as the simulation is computing.
 Once this has completed, messages will appear in the terminal reporting
 the progress of the simulation.
 
\end_layout

\begin_layout Standard
After running the 'betse try' command, if you go back to the directory where
 you placed and ran the BETSE executable, you should see a new directory
 called 'sample_sim' inside it.
 Inside of this 'sample_sim' directory, you should find a default configuration
 file called 'sample_sim.yaml', as well as an 'init' directory.
 Inside the 'init' directory is a 'results_a' directory, where you should
 see the saved 'plot while solving' animation as a set of png images.
 
\end_layout

\begin_layout Standard
The default simulation run using the 'betse try' command studies a 150 
\begin_inset Formula $\mu m$
\end_inset

 cluster of cells (approximately 83 cells) on an irregular lattice.
 An initialization is run for 5 seconds, which is followed by a simulation
 run for 5 seconds.
 From 1 to 2 seconds of the simulation run, the membranes of a cluster of
 cells in the bottom right region of the cluster have increased permeability
 to Na+ ions, leading to a temporary depolarization.
 
\end_layout

\begin_layout Subsection
Command Line Tips
\end_layout

\begin_layout Standard
Managing paths at the command line can be a bit cumbersome.
 Therefore, we suggest making BETSE more user friendly by going through
 the following sequence:
\end_layout

\begin_layout Standard
Copy the operating-system-specific BETSE executable deliverable to a new
 folder on your computer.
 We suggest making a folder called 'Applications' under your 'Home' directory
 (if it doesn't exist already), a folder inside the Applications folder
 called 'BETSE' and copying the BETSE executable, betse, into it.
\end_layout

\begin_layout Standard
At the command line we recommend you create a symlink from the original
 BETSE executable to a system-wide directory by typing the following command:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
ln
\begin_inset space \quad{}
\end_inset

-s
\begin_inset space \quad{}
\end_inset

~/Applications/BETSE/betse
\begin_inset space \quad{}
\end_inset

 /user/local/bin/betse 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
This should allow you to use BETSE from any directory on your computer.
 For example, if you have a folder 'Bio_Sims' inside your 'Documents' directory
 and want to store BETSE configuration files and simulation output in 'Bio_Sims'
, with the system-wide symlink to BETSE created you can easily work from
 the Bio_Sims folder by first changing the directory to look into Bio_Sims:
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cd
\begin_inset space \quad{}
\end_inset

 ~/Documents/Bio_Sims
\end_layout

\end_inset


\end_layout

\begin_layout Standard
...and then running BETSE from that directory, telling it to read a configuration
 file (e.g.
 my_config_file.yaml) that is directly inside the 'Bio_Sims' folder using
 the command:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse sim run my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
The BETSE Command Line Interface
\end_layout

\begin_layout Standard
The CLI features seven main commands that you can issue BETSE at the Terminal:
\end_layout

\begin_layout Enumerate
try
\begin_inset space \qquad{}
\end_inset

 
\emph on
seed, init, and sim a sample tissue simulation
\end_layout

\begin_layout Enumerate
info
\begin_inset space \qquad{}
\end_inset

 
\emph on
display instructive information about BETSE and the current system
\end_layout

\begin_layout Enumerate
config
\begin_inset space \qquad{}
\end_inset

 
\emph on
create a new tissue simulation configuration file 
\end_layout

\begin_layout Enumerate
seed
\begin_inset space \qquad{}
\end_inset

 
\emph on
make the cell cluster from parameters specified in a configuration file
\end_layout

\begin_layout Enumerate
init 
\begin_inset space \qquad{}
\end_inset

 
\emph on
initialize a previously created cell cluster with initialization-specific
 parameters specified in a configuration file
\end_layout

\begin_layout Enumerate
sim
\begin_inset space \qquad{}
\end_inset

 
\emph on
run the simulation for an initialized cluster using simulation-specific
 parameters specified in a configuration file 
\end_layout

\begin_layout Enumerate
plot
\begin_inset space \qquad{}
\end_inset

 
\emph on
plot previously created cell clusters, initialization or simulation runs
 (uses sub-commands)
\end_layout

\begin_layout Standard
To determine if a BETSE executable is active in a directory and see a high-level
 help message, simply type:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To check if BETSE will simulate properly on your computer and obtain a straightf
orwards taste of how BETSE works, simply type the 'try' command: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse try
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To determine where various files (such as log files) live on your system,
 and to obtain all sorts of meta-data information about BETSE, type the
 'info' command:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse info
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 'betse sim' command has six sub-commands, all of which are essential
 for running simulations with BETSE.
\end_layout

\begin_layout Standard
First of all, to create a default configuration file in a directory of your
 choice, type the 'config' command along with a path to where you'd like
 the file to be created:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout

\family typewriter
./betse config ~/BioSims/First_sim/my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
As written above, this 'config' command will create a file called 'my_config_fil
e.yaml' in the directory 'Home/BioSims/First_sim/.
 Of course, you can specify whatever directory and filename you wish for
 the config file, but we'll remain consistent with the location and filename
 of a configuration file at the '~/BioSims/First_sim/my_config_file.yaml'
 path for this example.
\end_layout

\begin_layout Standard
To change settings of the cell cluster, initialization, and simulation,
 you'll need to locate the 'my_config_file.yaml' on your system, open it
 in a text editor, and make the desired changes.
 
\end_layout

\begin_layout Standard
First, the cell cluster and (optionally) environmental spaces must be set
 up for computation.
 To do this, with the outcome determined by settings in the configuration
 file, use the 'seed' command:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse seed ~/BioSims/First_sim/my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To run an initialization using a config file and a cell cluster previously
 created, use the 'init' command, specifying the path and filename of the
 config file controlling the scenario you want to run:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse init ~/BioSims/First_sim/my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
After creating the cell cluster and running the initialization, use the
 'sim' command, specifying the path and filename of the config file controlling
 the scenario you want to simulate.
 If a world or initialization file aren't found under the path and filename
 listed under 'Initialization Settings' section of the config file, BETSE
 will automatically seed a cell cluster and/or do an initialization before
 getting to the simulation run:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse sim ~/BioSims/First_sim/my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
After creating a cell cluster (seed), running an initialization (init),
 or completing a full simulation (sim), you can load, plot, and save the
 stored data.
 It's possible to change settings in the 
\emph on
Results
\emph default
 section of the configuration file to alter the appearance and type of plots
 that are created with the plot command.
 To plot a previously created cell clusters, initializations, or simulations
 use the 'plot' command with one of three subcommands: 
\end_layout

\begin_layout Standard
Load and plot the cell cluster:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse plot seed ~/BioSims/First_sim/my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To load and plot an existing initialization:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse plot init ~/BioSims/First_sim/config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
And to load and plot a previously run simulation:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse plot sim ~/BioSims/First_sim/config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The config file tells the computer where to save all files, and these same
 paths in the config file tell the computer where to find files to load
 and plot.
 
\end_layout

\begin_layout Standard
Help messages at the Terminal can be accessed for commands by adding '-h'
 or '--help' after the command name, for example:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse sim --help
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note, at any time if you wish to abort an initialization or simulation,
 at the Terminal simply press (on Mac you may need to press ctrl c many
 times to get it to kill the program):
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
ctrl c
\end_layout

\end_inset


\end_layout

\begin_layout Section
The Configuration File
\begin_inset CommandInset label
LatexCommand label
name "sec:The-Configuration-File"

\end_inset


\end_layout

\begin_layout Standard
The configuration file allows you to have control over what happens during
 BETSE initializations, simulations, and results export and visualization.
\end_layout

\begin_layout Standard
In order to change settings and variables in BETSE, you simply open up a
 configuration file in a text editor and set the values to what you wish.
 You then run the BETSE program with that configuration file's path and
 name specified at the command line (see Section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Basic-Workflow-and"

\end_inset

 ).
 
\end_layout

\begin_layout Subsection
How to Make Default Config Files
\end_layout

\begin_layout Standard
To create a default configuration file that you can edit further, you have
 two command-line choices: 
\end_layout

\begin_layout Standard
You could run the 'try' command:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse try
\end_layout

\end_inset


\end_layout

\begin_layout Standard
...in which case you'll find a 'sample_sim.yaml' file inside a folder called
 'sample_sim' in the directory where you're running BETSE.
\end_layout

\begin_layout Standard
Or, you could run simply the 'config' command:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse config ~/Documents/bio_sims/my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
...in which case you'll find a 'my_config_file.yaml' file created inside a folder
 called 'bio_sims' in the 'Documents' folder under your 'Home' directory.
 You can obviously change the directory and filename to whatever you wish,
 but it should end with '.yaml'.
\end_layout

\begin_layout Standard
You can also just copy, paste, and rename any BETSE config file into a directory
 of your choice using the graphical system navigator of your operating system
 (e.g.
 
\emph on
Nautilus
\emph default
 on Linux or 
\emph on
Finder
\emph default
 on Mac).
 
\end_layout

\begin_layout Subsection
Basic Structure of Config Files
\end_layout

\begin_layout Standard
Each BETSE config file has 11 sections:
\end_layout

\begin_layout Enumerate
File Handling 
\emph on
(specify paths for saving/loading cell cluster, initialization runs, simulation
 runs, and results output)
\end_layout

\begin_layout Enumerate
Initialization Settings 
\emph on
(settings specific to the initialization run)
\end_layout

\begin_layout Enumerate
Simulation Settings 
\emph on
(settings specific to the simulation run)
\end_layout

\begin_layout Enumerate
General Options 
\emph on
(specify main options like what ions you want to include -- these parameters
 are fixed to the initialization run and propagated through subsequent simulatio
ns loading that initialization)
\end_layout

\begin_layout Enumerate
World Variables 
\emph on
(specify aspects of the cell, cluster, and gap junction network -- these
 parameters are fixed to the initialization run and propagated through subsequen
t simulations loading that initialization)
\end_layout

\begin_layout Enumerate
Global Interventions 
\emph on
(schedule events applying to the whole environment or cluster, such as the
 addition or pharmacological agents or blocking gap junctions)
\end_layout

\begin_layout Enumerate
Tissue Designation 
\emph on
(tell BETSE what bitmaps define the cluster and tissue regions, specify
 properties of tissue profiles, specify global boundary profiles)
\end_layout

\begin_layout Enumerate
Targeted Interventions 
\emph on
(schedule events, such as changing membrane permeabilities, that apply to
 specify tissue or global boundary profiles) 
\end_layout

\begin_layout Enumerate
Dynamic Ion Channels 
\emph on
(include dynamically responding channels such as voltage-gated Na+, which
 apply to specific tissue profiles)
\end_layout

\begin_layout Enumerate
Results 
\emph on
(specify what plots, animations and exports to include, as well as their
 features)
\end_layout

\begin_layout Enumerate
Internal Use Only 
\emph on
(change variables relating to the inner-workings of the simulation)
\end_layout

\begin_layout Subsection
Config Files and YAML
\end_layout

\begin_layout Standard
The configuration file is written in a computer language called 
\emph on
YAML
\emph default
, which is fairly easy for both humans and the Python BETSE program to read.
 However, because the configuration file is a little computer script, when
 editing it you have to be careful not change things that will make it non-reada
ble by the BETSE program.
 For example, it is essential that the line indentations (tabs) are maintained
 in their current order, and that only variable assignments are changed.
 Variable names must not be changed.
 In the file, comments intended only for human users, and that are not read
 by the BETSE program, are prefixed by a "#" and may be edited as you wish.
 Likewise, feel free to add in new # prefixed comment lines to any BETSE
 config file.
 
\end_layout

\begin_layout Standard
For more information on the 
\emph on
YAML
\emph default
 language, please see:
\end_layout

\begin_layout Standard
\begin_inset CommandInset href
LatexCommand href
target "https://en.wikipedia.org/wiki/YAML"

\end_inset


\end_layout

\begin_layout Section
File Handling
\begin_inset CommandInset label
LatexCommand label
name "sub:Defining-Save/Load-Paths"

\end_inset


\end_layout

\begin_layout Subsection
Specifying File Save/Load Directories and Filenames
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configFileHandling.png
	lyxscale 80
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
File Handling
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-File-Handling"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
Initializations and simulations in BETSE automatically save all of their
 data as a '.betse' binary file that can be re-read and plotted afterwards,
 and there is also the option to automatically save all the plots, animations,
 and raw data exports for a simulation.
 The places where these auto-saves (and corresponding auto-loads) happen
 are defined in the BETSE configuration file.
 Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-File-Handling"

\end_inset

 shows the 
\emph on
File Handling
\emph default
 section of the configuration file, where you can specify the directory
 and file names for the init (init file saving), cell cluster (worldfile),
 sim (sim file saving) and any automatically saved and exported results
 (results file saving).
 
\end_layout

\begin_layout Standard
For portability, files and directories are configured as paths that are
 
\emph on
relative
\emph default
 to the location of the config file, rather than as 
\emph on
absolute
\emph default
 pathnames.
 For example, instead of defining the save/load path of the simulation as:
\end_layout

\begin_layout Standard
'/Documents/bio_sims/my_sim/sim_52.betse'
\end_layout

\begin_layout Standard
if the config file is located within the 'bio_sims' folder, under 'sim file
 saving' all you need to specify is a directory name of 'my_sim' and a file
 of: 'sim_init.betse' to acheive the desired result.
 
\end_layout

\begin_layout Standard
This usage of relative paths allows any folders containing your simulations
 and results to be safely moved to other locations or computers, without
 breaking the functionality of existing simulations.
 
\end_layout

\begin_layout Subsection
Using a Simulation as and Initialization
\end_layout

\begin_layout Standard
The difference between an init and sim is that an init does not implement
 any of the global or targeted interventions or dynamic ion channels, yet
 sometimes it's desirable to set the scene of a simulation with dynamics
 present.
 While the typical course of events is to do an initialization (init) first,
 which saves a *.betse binary to the init directory and filename, it's possible
 to seed a world, do an init, do a sim (sim a), and to then load the sim
 as the initialization to another sim (sim b).
 To do this, after running the first sim (sim a), simply use the sim file
 created as an initialization by specifying the path and filename of sim
 a in the 'init file saving' fields of the config file, and supply a new
 directory and filename to save the upcoming sim (sim b) in the 'sim file
 saving' fields.
 
\end_layout

\begin_layout Section
Initialization Settings
\begin_inset CommandInset label
LatexCommand label
name "sec:Initialization-Settings"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configInit.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
Initialization Settings
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-Initialization-Settings"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Each simulation that is run in BETSE requires an initialization run.
 The initialization run creates the cell cluster and performs a simulation
 without any of the features listed in the 
\emph on
Global Interventions, Targeted Interventions
\emph default
 or 
\emph on
Dynamic Channels
\emph default
 sections being active, which allows the modelled bioelectric system to
 be in, or closer to, cell resting V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

.
 Whenever you try to run a simulation in BETSE using the 'betse sim' command,
 it will check to see if you have an initialization.
 If not, it will go ahead and run an initialization first (unless you change
 the 
\emph on
Simulation Settings
\emph default
 field 'automatically run initialization' to False).
 Otherwise, you can also run an initialization without running a sim using
 the 'init' command:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse init my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
There are two obvious cases where you'd want to run an initialization separately
 from a sim: 1) you want to see what the world looks like and know what
 the numbered cell indices are before targeting individual cells with interventi
ons and dynamics in the actual simulation or 2) you want to change something
 about 
\emph on
General Options
\emph default
 or 
\emph on
World Variables
\emph default
 and so need to run another initialization to override values established
 by the first initialization so they appear in your simulations.
 
\end_layout

\begin_layout Standard
The 
\emph on
Initialization Settings
\emph default
 of the config file allow you to specify settings for the initialization
 run.
 
\end_layout

\begin_layout Subsection
Initialization Time Profiles
\end_layout

\begin_layout Standard
Choose a time profile for how the init will be computed by editing the 'time
 profile' field.
 By typing 'initialize' you get the pre-defined time profile settings for
 the initialization and don't have to worry about details.
 Otherwise, if you want more control over how the initialization will be
 carried out, type 'custom init' here.
 The settings for this 'custom init' time-profile will be controlled by
 the fields under the 'custom init time profile' header of the configuration
 file (described below).
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
time profile: 'initialize'
\end_layout

\end_inset


\end_layout

\begin_layout Standard
After choosing a time profile, specify the time for the initialization run
 in seconds [s].
 We recommend 5 to 30 s of initialization.
 Note this 'total time' setting is overridden if you are using 'cutom init'
 with settings defined in the 'custom init time profile' header (described
 below).
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
total time: 5
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Custom Initialization Time Profile
\end_layout

\begin_layout Standard
If you have chosen the 'custom init' time profile, you'll need to set further
 details relating to the simulation, which are found under the 'custom init
 time profile' heading.
 The first setting is the 'time step', which is the amount by which the
 simulation increases world-time in each calculation loop.
 Smaller time steps will give you more stability and more accuracy, at the
 expense of increased simulation time and memory as each time step represents
 a computational loop.
 Simulation step-size is defined in seconds [s].
 The recommended range for 'time step' is 1e-3 or smaller for init runs.
 Next, use the 'total time' field to decide how long you want to run the
 initialization, defined in seconds [s].
 The recommended range is from 5 to 60 s.
 The 'sampling rate' allows you to specify a time period in seconds [s]
 to re-sample data from the init run, so that you are not sampling data
 at each time step.
 For an init run, the recommended re-sampling range is from 0.1 to 1 s.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
custom init time profile:
\end_layout

\begin_layout Plain Layout
\noindent

\family typewriter
\begin_inset space \qquad{}
\end_inset

time step: 1e-2
\end_layout

\begin_layout Plain Layout
\paragraph_spacing single
\noindent

\family typewriter
\begin_inset space \qquad{}
\end_inset

total time: 100
\end_layout

\begin_layout Plain Layout
\paragraph_spacing single
\noindent

\family typewriter
\begin_inset space \qquad{}
\end_inset

sampling rate: 1.0
\end_layout

\end_inset


\end_layout

\begin_layout Section
Simulation Settings
\begin_inset CommandInset label
LatexCommand label
name "sec:Simulation-Settings"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configSim.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
Simulation Settings
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-Simulation-Settings"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
Simulation Settings 
\emph default
section of the config file allows you to specify things particular to how
 the actual simulation gets carried out.
 To run a simulation type: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
./betse sim my_config_file.yaml
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Every simulation requires the creation of a cell cluster using 'seed', proceeded
 by an initialization 'init' to ensure the system is in steady state (at
 resting potential) when the simulation begins.
 In the case that a cell cluster and/or initialization file is not found,
 use the 'automatically run initialization' field to specify whether or
 not you wish to automatically create these features if none exist at the
 time of your run call.
 If 'automatically run initialization' is set to False, when initializations
 are not found the program will crash with an appropriate error message
 and you'll need to run the initialization manually by calling the 'betse
 init' command.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
automatically run initialization: True
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Simulation Time Profiles
\end_layout

\begin_layout Standard
The 'time profile' for the simulation lets you choose from the pre-defined
 profiles 'simulate somatic' and 'simulate excitable'.
 The profile 'simulate somatic' is intended for longer simulations (on the
 order of minutes) for cells with slower dynamical behaviors (e.g.
 cells without voltage-gated sodium and potassium channels, but possibly
 with calcium dynamics).
 The profile 'simulate excitable' is intended for short simulations (on
 the order of a few hundred miliseconds to a couple of seconds) for cells
 with rapid dynamical behaviors (e.g.
 cells with voltage-gated sodium and potassium channels).
 If you desire more control over how the simulation is carried out, type
 'custom sim' for the 'time profile' field, which gives additional settings
 that are specified under the 'custom sim time profile' field.
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
time profile: 'simulate excitable'
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you've chosen 'simulate excitable' or 'simulate somatic' for your 'time
 profile', decide on the total time for the simulation in seconds [s].
 We recommend 10 s to several minutes of world-time for the 'simulate_somatic'
 time profile and 0.1 to 5 seconds for 'simulate_excitable' time profile.
 Note this is over-ridden if you are using 'custom sim'.
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
total time: 0.50
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Custom Simulation Time Profiles
\end_layout

\begin_layout Standard
If you have chosen the 'custom sim' time profile, you'll need to set further
 details relating to the simulation, which are located under the 'custom
 sim time profile' heading.
 The first setting is the 'time step', which is the amount by which the
 simulation increases world-time in each calculation loop.
 Smaller time steps will give you more stability and more accuracy, at the
 expense of increased simulation time and memory.
 Simulation step-size is defined in seconds.
 The recommended range for 'time step' is 1e-4 to 1e-3 s for sim runs.
 Next, use the 'total time' field to decide how long you want to run the
 simulation, defined in seconds.
 The 'sampling rate' allows you to specify a time period in seconds to re-sample
 data from the init run, so that you are not sampling data at each time
 step.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout

\family typewriter
custom sim time profile:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

time step: 5e-3
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

total time: 10.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

sampling rate: 0.1
\end_layout

\end_inset


\end_layout

\begin_layout Section
General Options
\begin_inset CommandInset label
LatexCommand label
name "sec:General-Options"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configGenOps.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
General Options
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-General-Options"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
General Options
\emph default
 section of the configuration file is where you specify the kinds of ions
 you wish to include in the simulation and their initial cell and environmental
 concentrations, as well as global features such as additional types of
 ion pumps (e.g.
 H,K-ATPase).
 
\end_layout

\begin_layout Standard
To ensure synchronization between initialization and simulation runs, 
\emph on
General Options
\emph default
 will always default to values of the initialization.
 In other words, you are not able to change the ion profile when calling
 'betse sim'; only when calling 'betse init'.
 
\end_layout

\begin_layout Subsection
Grid
\end_layout

\begin_layout Standard
BETSE creates a square grid, which is used to interpolate cell-specific
 data such as ionic currents to prepare streamline plots, as well as to
 compute properties in environmental spaces (when this option is implemented).
 You can specify the resolution of the square grid (as the number of ticks
 of the horizontal and vertical axes) using the 'grid size' option under
 the 
\emph on
General Options
\emph default
 section: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout
grid size: 50 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Grid sizes are recommended to not be lower than 20 and to not exceed 60.
 
\end_layout

\begin_layout Subsection
Simulate a Full Environment
\begin_inset CommandInset label
LatexCommand label
name "sub:Simulate-a-Full"

\end_inset


\end_layout

\begin_layout Standard
A single line of the 
\emph on
General Options
\emph default
 section controls the major feature of whether the cell cluster, initialization
 and simulations model a full environment with extracellular spaces around
 each cell and optional tight and adherens cell-cell junction settings:
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
simulate ECM: True 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If simulate ECM is False, the cell cluster will be created without environmental
 spaces, and initializations and simulations will assume cells flux out
 to a global environment with instantaneous mixing to the larger whole.
 
\end_layout

\begin_layout Subsection
Ion Profiles
\end_layout

\begin_layout Standard
First use the 'ion profile' field to specify an ion profile to be used in
 the simulation.
 The values specified in the ion profile are the initial condition values
 for ion concentrations inside and out of the cell at the beginning of the
 initialization simulation.
 To make things a bit easier, there are three pre-made default profiles
 that you can choose for this field:
\end_layout

\begin_layout Itemize
'basic' 
\emph on
(Na
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

, K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

, negatively charged proteins P
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

, and a charge balance anion M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

)
\end_layout

\begin_layout Itemize
'basic_Ca' 
\emph on
(Na
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

, K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

, Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

, negatively charged proteins P
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

, and a charge balance anion M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

)
\end_layout

\begin_layout Itemize
'animal' 
\emph on
(Na
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

, K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

, Cl
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

, Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

, H
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

, negatively charged proteins P
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

, and a charge balance anion M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

 representing HCO
\begin_inset script subscript

\begin_layout Plain Layout
3
\end_layout

\end_inset


\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

)
\end_layout

\begin_layout Standard
In the 'animal' profile the charge-balance anion M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

 represents HCO
\begin_inset script subscript

\begin_layout Plain Layout
3
\end_layout

\end_inset


\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

 (bicarbonate).
 Note as ion number increases, time to run an initialization or simulation
 increases proportionally (
\emph on
i.e.

\emph default
 it will take about 1.75 times longer to run a simulation with the 'animal'
 profile compared to the 'basic' profile), and memory demands increase proportio
nally.
 
\end_layout

\begin_layout Standard
In addition to these four default profiles, you can specify 'customized'
 for the 'ion profile' field, which allows to you use your own settings.
 If the 'customized' profile is selected, initial ion levels in the cell
 and environment must be defined under the 'customized ion profile' header
 at the end of the 
\emph on
General Options
\emph default
 section (described in sub-section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Customized-Ion-Settings"

\end_inset

).
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
ion profile: 'basic'
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Optional Ion Pumps
\end_layout

\begin_layout Standard
To include H,K-ATPase pumps in the simulation, set the 'HKATPase pump' field
 to True.
 Note, this setting only works for an ion profile with H
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 ions ('animal' or 'customized'), otherwise it is simply ignored.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
HKATPase pump: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To include plasma membrane V-ATPase pumps in the simulation, set the 'VATPase
 pump' field to True.
 Note, this only works for an ion profile with H
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 ions ('animal' or 'customized'), otherwise it is simply ignored.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
VATPase pump: True
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Morphogen Properties
\end_layout

\begin_layout Standard
BETSE optionally includes a substance in cells and/or the environment, which
 has a flexible variety of parameters associated with it, and can optionally
 target a cell ion channel in a concentration-dependent manner from either
 its intra- or extracellular (if 'simulate ECM' is True) concentrations.
 This generic substance is called the 'morphogen' and its properties can
 be defined under the 'morphogen properties' section of 
\emph on
General Options
\emph default
.
 
\end_layout

\begin_layout Standard
To include the morphogen in the simulation, set the 'include morphogen'
 field to True.
 
\end_layout

\begin_layout Standard
The adjustable properties of the morphogen are: 'Dm', the morphogen's membrane
 diffusion coefficient [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s]; 'Do' the gap junction and free environment diffusion constant [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s]; 'z' the charge of the morphogen (oxidation state); 'env conc' and 'cell
 conc', the initial concentration of morphogen in the environment and cell
 [mmol/L or equivalently mol/m
\begin_inset script superscript

\begin_layout Plain Layout
3
\end_layout

\end_inset

]; the 'ion channel target', which may be set to 'None' for no activity
 or to the name of an ion including 'Na', 'K', 'Cl' or 'Ca' to target a
 corresponding membrane channel (the ion must be included in your simulation!).
 The 'target Hill coefficient', and 'target Hill exponent' represent the
 half-max-value and Hill exponent for the open state of the ion channel
 as a function of morphogen concentration, which is controlled by a 
\begin_inset CommandInset href
LatexCommand href
name "Hill equation"
target "https://en.wikipedia.org/wiki/Hill_equation_%28biochemistry%29"

\end_inset

.
 The field 'peak channel opening' specifies the maximum value of the cell
 membrane diffusion constant to the ion channel target in units of [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s].
 Finally, the field 'acts extracellularly' specifies whether the ion channel
 opens with extracellular concentration of the morphogen (True) or intracellular
 concentration (False).
 The ion channel effects of the morphogen concentration are only implemented
 in simulations and do not occur in initializations.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
morphogen properties:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

include morphogen: True 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm: 1.0e-12 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Do: 1.0e-9 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

z: -1 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

env conc: 1.0e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cell conc: 1.0e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

ion channel target: None 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

target Hill coefficient: 1.0e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

target Hill exponent: 1.0 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

peak channel opening: 1e-16
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

acts extracellularly: False
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Noise
\end_layout

\begin_layout Standard
In BETSE simulations, there are two types of noise: a constant (static)
 noise representing a variation in V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 for individual cells and determined by adding a variation in the level
 of K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 leak channels on cell membranes, and a flickering (dynamic) noise represented
 a small random walk on V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 created by slightly altering the concentration of negatively charged proteins
 in cells.
 Note that both types of noise can cause simulation instability (and consequent
 program crash with error message) and if this is the case either decrease
 the 'time step' by using the 'custom init' or 'custom sim' time profiles
 in the 
\emph on
Initialization Settings
\emph default
 or 
\emph on
Simulation Settings
\emph default
 sections.
 Alternatively, try decreasing the level of noise.
 
\end_layout

\begin_layout Standard
Note that as the dynamic noise is tied to protein levels (P
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

) this ion needs to be included in the ion profile (this is only a concern
 if you're using a 'custom ion profile' and set 'include P-' to False, see
 sub-section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Customized-Ion-Settings"

\end_inset

 for details).
 
\end_layout

\begin_layout Standard
To specify static noise, simply change the value of 'static noise level'
 to something above 0.
 An appropriate range is 0 (all cells equivalent; no static noise) to 10.0
 (very high variation).
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
static noise level: 0
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If dynamic noise is desired, first set the 'dynamic noise' field to True.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
dynamic noise: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Next, set the level of dynamic noise in the 'dynamic noise level' field.
 This value has a big influence on the simulation, so it's best to keep
 values small.
 An appropriate range is from 0 to 1e-6.
 Note higher values may very well cause simulation instability, so be prepared
 to decrease your simulation time step.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
dynamic noise level: 1e-7
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Customized Ion Settings
\begin_inset CommandInset label
LatexCommand label
name "sub:Customized-Ion-Settings"

\end_inset


\end_layout

\begin_layout Standard
If 'custom' is specified in the 'ion profile' setting, you will need to
 define what ions you wish to include in your simulation and specify all
 of the initial values for these ions in the cytosolic and environmental
 space.
 Note that Na
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 and K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 ions are included by default in all simulations.
 In addition, all simulations will include a charge balance anion M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

.
 The concentration of M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

 is not specified by the user; rather, it is calculated based on the amount
 of negative charge needed to make the cytosolic and environmental spaces
 electrically neutral.
 As the charge of M- is negative, both the extracellular and cytosolic levels
 of all additional ions you specify must add up to a net positive charge
 (it must be a net positive so it can be charge balanced by the anion M-).
 If you specify an ion concentrations in the 'customized ion profile' settings
 for the cytosolic or environmental spaces that add up to a net negative
 charge, the program will crash with an error message to go back and make
 sure the net balance of ions you include is positive.
 
\end_layout

\begin_layout Standard
If any of the ions in the list are set to False, they won't be included
 in the initialization or simulation, and the value specified in the cytosolic
 or environmental concentration fields will be ignored.
 Note that including H+ automatically generates a bicarbonate buffer.
 Finally, for realistic V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 and to include dynamic noise it is recommended to always include negatively
 charged proteins, P
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
The field 'endoplasmic reticulum Ca2+' specifies the starting level of calcium
 in the endoplasmic reticulum stores and is only used if calcium dynamics
 are set to True in the Dynamic Channels section of the configuration file.
 
\end_layout

\begin_layout Standard
The units of all concentrations are [mmol/L] or equivalently [mol/m
\begin_inset script superscript

\begin_layout Plain Layout
3
\end_layout

\end_inset

].
 The values specified in the ion profile are the initial condition values
 at the beginning of the initialization simulation.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
customized ion profile:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

include Cl-: False
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

include Ca2+: False
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

include H+: False
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

include P-: False
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

extracellular Na+ concentration: 145.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

extracellular K+ concentration: 5.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

extracellular Ca2+ concentration: 1.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

extracellular H+ concentration: 3.98e-5
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

extracellular protein- concentration: 9.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cytosolic Na+ concentration: 5.4
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cytosolic K+ concentration: 140.44
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cytosolic Cl- concentration: 6.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cytosolic Ca2+ concentration: 1.0e-3
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cytosolic H+ concentration: 6.31e-5
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cytosolic protein- concentration: 138.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

endoplasmic reticulum Ca2+: 0.5
\end_layout

\end_inset


\end_layout

\begin_layout Section
World Variables
\begin_inset CommandInset label
LatexCommand label
name "sec:World-Variables"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configWorldVars.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
World Variables
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-World-Variables"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
In BETSE, the 'world' refers to cell geometric properties, the size of the
 cluster, and the properties of the environment such as size and temperature.
 These variables are common to both initialization and simulation runs.
 
\end_layout

\begin_layout Standard
To ensure synchronization between initialization and simulation runs, world
 variables will always default to those of the initialization.
 In other words, you are not able to change the geometry of cells or the
 cluster when calling 'betse sim'; only when calling 'betse init'.
 If world variables are altered after the initialization, they will not
 be implemented; rather, BETSE will default to whatever world variables
 existed in the initialization loaded from the Initialization Settings path.
 
\end_layout

\begin_layout Subsection
Cell and Cluster Geometric Features
\end_layout

\begin_layout Standard
Currently, the world is square (x=y) and the cell cluster based on a circular
 shape.
 Specify the dimension of the world space using the 'world x' field, with
 the value in meters [m].
 The recommended range for world dimension is from 100e-6 to 1000e-6 m (note:
 the RAM memory and disk-space used for a 500x500 um world is approximately
 1 Gb, growing from only ~60 Mb for a 200x200 um world, see Tables 
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Disk-space-used"

\end_inset

 and 
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Maxium-RAM-used"

\end_inset

).
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
world x: 200e-6
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Next specify the radius of a single cell in meters [m].
 The recommended range is from 3.5e-6 to 20e-6 m.
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cell radius: 5e-6 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Use the 'cell height' field to specify the height of a cell in the z-direction
 [m].
 Although BETSE is a 2D simulator, cell height is used to calculate volume
 and lateral surface area.
 The recommended range is from 1.0e-6 to 10e-6 m.
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cell height: 5.0e-6
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Specify the spacing between cells [m].
 The recommended value is 26.0e-9 m for animal cells.
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cell spacing: 26.0e-9
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Specify the noise level for the lattice using the 'lattice disorder' field.
 This parameter deviates cell center points from a square grid with random
 perturbations (see Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Lattice-disorder-of"

\end_inset

).
 If 'lattice disorder' is equal to 0, a perfect square grid arrangement
 of cells is created; higher values generate irregular (and arguably more
 bio-similar) grids.
 The recommended range is from 0 to 0.9.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
lattice disorder: 0.8
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/vmem_gj_43_SquareVersusVoroniLattice.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Lattice disorder of 0.8 (left image) and 0.0 (right image).
\begin_inset CommandInset label
LatexCommand label
name "fig:Lattice-disorder-of"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Base Environmental Properties
\end_layout

\begin_layout Standard
Specify the temperature of the world in degrees Kelvin [K].
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
temperature: 310
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Include gravity (only has an effect if also simulating electroosmotic fluid
 flow).
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
gravity: True
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Electroosmosis
\end_layout

\begin_layout Standard
In bioelectrical systems, net ionic charge may exist in both intra and extracell
ular spaces, in combination with electric fields.
 BETSE hypothesizes that emergent electric fields of the cluster can exert
 forces on this ionic charge, which constitute body forces on the fluidic
 medium, and may result in electroosmotic flows.
 
\end_layout

\begin_layout Standard
This electroosmotic flow can be optionally simulated in BETSE.
 If 'simulate ECM' (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Simulate-a-Full"

\end_inset

) is True, this electroosmosis will be considered in both the intra- and
 extra- cellular environments.
 If 'simulate ECM' is false, only electroosmotic flows between gap junction
 connected cells will be considered.
 
\end_layout

\begin_layout Standard
You can easily turn the electroosmosis simulation on and off using the line
 under 
\emph on
World Variable
\emph default
 section of the config file:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
electroosmosis: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Note that the decision to use electroosmosis must be made at the time of
 world seeding, otherwise the simulation won't be implemented as the required
 solution matrices won't be created.
 Electroosmosis can, however, be shut off for initializations and simulations
 after world seeding.
 Electroosmosis creates a range of new solving matrices, so adds significantly
 to the disk space and RAM used.
 
\end_layout

\begin_layout Standard
Details regarding how electroosmosis is implemented can be found in the
 theory section (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Electroosmosis"

\end_inset

) of this document.
 
\end_layout

\begin_layout Subsection
Ion Pump/Channel Movements
\end_layout

\begin_layout Standard
If 'simulate ECM' (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Simulate-a-Full"

\end_inset

) is True, BETSE can optionally model lateral movement of membrane-bound
 ion pumps and channels under the action of forces from electric fields
 or electroosmotic flows (if applicable) that are tangent to the membrane.
 To turn this feature on and adjust settings, see the 'channel electroosmosis'
 settings of the 
\emph on
World Variables
\emph default
 section of the config file: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
channel electroosmosis: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

turn on: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

channel charge: -1
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

membrane mobility: 1e-10
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To turn the effect on, use 'turn on: True'.
 To set the charge of all ion channels and pumps included in your simulation
 use 'channel charge', and to specify how easily the channels and pumps
 move with lateral forces use the 'membrane mobility' setting (recommended
 range from 1e-9 to 1e-12).
 
\end_layout

\begin_layout Standard
Details regarding how ion pump/channel movements are handled can be found
 in the theory section (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Ion-Pumps-and"

\end_inset

) of this document.
 
\end_layout

\begin_layout Subsection
Gap Junction Properties
\end_layout

\begin_layout Standard
Cells in the cluster are connected by voltage-sensitive gap junctions.
 Gap junction properties are controlled under the 'gap junctions' portion
 of the 
\emph on
World Variables
\emph default
 section of the config file.
\end_layout

\begin_layout Standard
Use the 'search distance' field to change the distance to search for nearest
 neighbors when on a particular cell center point (see the effect of search
 distance in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Search-distance-of"

\end_inset

).
 The 'search distance' field is a multiplier of the average cell diameter.
 A range of 1.1 to 2.5 is suggested.
 A warning that large search distances (>2.0) can produce extremely long
 simulation times due to a large increase in the number of calculations
 required when each cell has numerous neighbors.
 High search distances can also result in simulation instability, and may
 therefore require smaller simulation time steps.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout

\family typewriter
search distance: 1.5
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/vmem_gj_43_differentSearchRadii.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Search distance of 1.5 (left image) and 2.5 (right image).
\begin_inset CommandInset label
LatexCommand label
name "fig:Search-distance-of"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 'gap junction surface area' field controls the base conductivity of
 the gap junctions, and is defined in terms of the fraction of cell membrane
 area that is allocated to gap junctions, therefore, the gap junction surface
 area parameter is unitless.
 Gap junctions of 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-6
\end_layout

\end_inset

 or smaller are effectively closed, 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-4
\end_layout

\end_inset

 - 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-5
\end_layout

\end_inset

 can be considered low gap junction conductivity, 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 to 5.0e
\begin_inset script superscript

\begin_layout Plain Layout
-4
\end_layout

\end_inset

 is moderate gap junction conductivity, and 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-2 
\end_layout

\end_inset

to 5.0e
\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 very high gap junction conductivity.
 Note that simulations using a time step of 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 s can generally handle gap junction surface areas of 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 or smaller.
 Gap junction surface areas of 5.0e
\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 to 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-2
\end_layout

\end_inset

 require smaller time steps of 1.0e
\begin_inset script superscript

\begin_layout Plain Layout
-4
\end_layout

\end_inset

 s.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout

\family typewriter
gap junction surface area: 1.0e-4
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Gap junctions are optionally voltage sensitive, meaning they open and close
 depending on the value of intercellular voltages.
 To set gap junctions as voltage sensitive, use the field under the gap
 junctions section of 
\emph on
World Variables
\emph default
: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
voltage sensitive gj: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The voltage sensitivity of gap junctions has significant effects on the
 cluster's electrochemical dynamics.
 Use the 'gj voltage threshold' field to specify the cell-cell voltage at
 which the gap junctions close in volts [V].
 The suggested range is from 10e
\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 to 50e
\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 V.
 Note that a sigmoidal curve is used to control gap junction closure, so
 this 'gj voltage threshold' represents the voltage at which gap junctions
 are half closed.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
gj voltage threshold: 15e-3
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Use the 'gj voltage window' field to specify the range over which gap junctions
 go from open to shut [V].
 The suggested window value is from 5e-3 to 40e-3.
 Since sigmoidal curves are being used to control gap junction closure,
 this window specifies how far below the threshold the gap junction begins
 to close, and how far above the threshold the gap junction becomes fully
 closed.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout

\family typewriter
gj voltage window: 10e-3
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Finally, gap junctions may optionally respond to the relative amount of
 current they carry to enter into a feedback cycle to become more conductive
 the more current they carry.
 This feature may be enabled using the 'gj flux sensitive' field:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout

\family typewriter
gj flux sensitive: True
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Cell-Cell Adhesions
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/circular cluster/fig_env_diffusion_weights.png
	lyxscale 80
	width 80text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
When simulating a full environment, BETSE automatically detects the outer
 boundary of your cell cluster and can assign different diffusion constants
 to the outer media, outer cluster boundary, and internal cells.
 This 'Logarithm of Environmental Diffusion Weigh Matrix' figure (produced
 automatically when plotting the seeded cluster when 'simulate ECM' is True)
 shows extracellular spaces of the cluster boundary to have 1e
\begin_inset script superscript

\begin_layout Plain Layout
-7
\end_layout

\end_inset

 times lower diffusion constants than free media surrounding the cluster,
 while interior cells have 1e
\begin_inset script superscript

\begin_layout Plain Layout
-2
\end_layout

\end_inset

 times lower diffusion constants than the free media.
 
\begin_inset CommandInset label
LatexCommand label
name "fig:diffWeighMatrix"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
If 'simulate ECM' (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Simulate-a-Full"

\end_inset

) is True, BETSE considers cells to have extracellular environments.
 In real tissue, cells are often joined by tight junctions or adherens junctions
, which may limit diffusion around cells to various extents.
 
\end_layout

\begin_layout Standard
If simulating a full environment, you can optionally simulate the inclusion
 of tight junctions by using the 'tight junction scaling' field of the 
\emph on
World Variables
\emph default
 section of the config file: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
tight junction scaling: 1.0e-7
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 'tight junction scaling' factor you supply is used to multiply the free
 diffusion constants of all ions and substances included in your model,
 for the extracellular spaces of cells located at the outer boundary of
 the cell cluster (BETSE automatically detects the boundary for you).
 
\end_layout

\begin_layout Standard
Likewise, cell-cell connections within a cluster may have other types of
 junctions (e.g.
 adherens), which may alter diffusion around cells compared to free diffusion
 in liquid.
 To include the influence of internal cell-cell connections (i.e.
 those away from the outer cluster boundary), set the 'adherens junction
 scaling' factor:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
adherens junction scaling: 1.0e-2
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To get a better idea of the difference between the cluster boundary specific
 tight junction scaling and internal adherens junction scaling effects for
 an example cluster, see Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:diffWeighMatrix"

\end_inset

.
 
\end_layout

\begin_layout Standard
If you don't want to include the influence of tight junctions at the cluster
 boundary or adherens junctions for cells in the cluster, simply set the
 value of these two fields to 1.0.
 
\end_layout

\begin_layout Section
Global Interventions
\end_layout

\begin_layout Standard
Global Interventions are events that affect the state of the entire cell
 population or environment.
 At present you can specify a transient change to:
\end_layout

\begin_layout Itemize
Environmental K+ levels
\end_layout

\begin_layout Itemize
Enviromental Cl- levels
\end_layout

\begin_layout Itemize
Envirnomental Na+ levels
\end_layout

\begin_layout Itemize
Environmental morphogen levels (if included in simulation)
\end_layout

\begin_layout Itemize
World Temperature
\end_layout

\begin_layout Itemize
Block all gap junctions (or a randomly targeted sub-population of gap junctions)
\end_layout

\begin_layout Itemize
Block NaK-ATPase pumps
\end_layout

\begin_layout Itemize
Block HK-ATPase pumps (if included in simulation)
\end_layout

\begin_layout Itemize
Block V-ATPase pumps (if included in simulation)
\end_layout

\begin_layout Standard
To implement global scheduled changes, see the 
\emph on
Global Interventions
\emph default
 section of the config file, where there is a list of possible global interventi
ons and options under each type of change.
 Most of the global interventions are defined by text blocks that follow
 a similar format:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
change K env:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

event happens: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change start: 5 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change finish: 100 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change rate: 10 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

multiplier: 10
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To make the global intervention apply in your simulation run, set the 'event
 happens' field to True.
 Specify when in the simulation you want the property to start changing
 ('change start'), when you want the change to finish ('change finish'),
 the rate at which you desire a change to go from baseline to changed and
 vice versa ('change rate'), and the factor by which you want the change
 to deviate from baseline values ('multiplier').
 The times and rates are specified in seconds, while the multiplier is unit-less.
 
\end_layout

\begin_layout Standard
If 'simulate ECM' (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Simulate-a-Full"

\end_inset

) is True, when applying a global change to a concentration, BETSE introduces
 the altered concentration from the global boundaries of the environmental
 bounding box.
 Also, when a full envirnoment is simulating, changing the concentration
 of a particular ion must be charge balanced (i.e.
 you can't just add in pure K+ ions to the environment, it must come in
 as a salt with equal moles of an anion).
 Therefore, K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 is introduced as equal parts K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

& M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

, Cl
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

 as equal parts Na
\begin_inset script superscript

\begin_layout Plain Layout
+ 
\end_layout

\end_inset

& Cl
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

, and Na
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 as equal parts Na
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

& M
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset

.
 If 'simulate ECM' is False, the ion is simply introduced as the environmental
 charge and voltage are not a concern.
 
\end_layout

\begin_layout Standard
Note, the 'block gap junctions', 'block NaKATPase pump' and 'block HKATPase
 pump' headers do not have a 'multiplier' field as the block currently sets
 all activity to zero.
 When blocking gap junctions, you're able to specify the randomly targeted
 fraction of gap junctions to be blocked by typing an integer from 1 to
 100 in the 'random fraction' field: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
block gap junctions:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

event happens: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change start: 5 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change finish: 100 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change rate: 10 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

random fraction: 75
\end_layout

\end_inset


\end_layout

\begin_layout Section
Tissue Designation
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configTissueDesignation.png
	lyxscale 60
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
Tissue Designation
\emph default
 section of the configuration file.
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
Tissue Designation
\emph default
 section of BETSE config files is where you specify what bitmap images BETSE
 will read in and how to use them, as well as what tissue and boundary profiles
 will be defined and their features.
\end_layout

\begin_layout Subsection
Using Bitmaps to Control Cluster and Tissue Geometries
\begin_inset CommandInset label
LatexCommand label
name "sub:Using-Bitmaps-to"

\end_inset

 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/bitmap_example
	lyxscale 40
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Four *.png images that can be used to define the overall shape of the cluster
 (far left image) and three different tissue profiles.
\begin_inset CommandInset label
LatexCommand label
name "fig:Four-*.png-images"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/bitmapExample_cluster_mosaic2.png
	lyxscale 80
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
BETSE cell cluster and tissue profiles resulting from bitmap image set shown
 in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Four-*.png-images"

\end_inset

.
 Regions of the cluster that are scheduled to be amputated during a simulation
 ('cuts') are shown in black.
 
\begin_inset CommandInset label
LatexCommand label
name "fig:BETSE-cell-cluster"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
BETSE can read in an unlimited number of bitmap images that can be used
 to define the overall shape of your cell cluster, as well as to define
 spatial regions within the model that have different properties and dynamics
 (tissue profiles), or regions which are cut out of the model before an
 initialization or during a simulation.
 
\end_layout

\begin_layout Standard
These bitmap image sets can be created in any drawing program that supports
 the export of *.png images.
 When you create a default configuration file using the 'betse config ~/path_to_
my_config/config_file.yaml' command, a folder called 'geo' is also created.
 Geo includes three folders with default bitmap image sets suitable for
 use with BETSE.
 These are 'circle', 'ellipse' and 'planaria'.
 
\end_layout

\begin_layout Standard
Bitmap images you create yourself must have the following features:
\end_layout

\begin_layout Itemize
square images with equal number of pixels on each side (recommended 500
 x 500 pixels per image)
\end_layout

\begin_layout Itemize
pure white backgrounds
\end_layout

\begin_layout Itemize
area to define cluster or tissue region must be a solid black area
\end_layout

\begin_layout Itemize
*.png file format
\end_layout

\begin_layout Itemize
saved with file names and .png extension
\end_layout

\begin_layout Standard
Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Four-*.png-images"

\end_inset

 shows an example of four bitmap images from the geo/planaria folder that
 are used to create the cell cluster and tissue profiles in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:BETSE-cell-cluster"

\end_inset

.
\end_layout

\begin_layout Standard
To specify features of bitmaps used by BETSE see the 
\emph on
Tissue Designation
\emph default
 section of the config file under 'geometry defining bitmaps'.
 To use bitmaps, set the field 'use bitmap geometry control' to True.
 If you set this field to False, BETSE ignores any tissue profiles using
 bitmaps and defaults to a circular geometry.
 Tell BETSE what directory you want it to look for bitmaps in (this directory
 is relative to where the config file is located) using the field 'directory'.
 Finally, specify the total number of bitmaps that BETSE will try to read
 in using the field 'number of bitmaps'.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
geometry defining bitmaps:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

use bitmap geometry control: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

directory: geo/planaria 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

number of bitmaps: 4 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

bitmap 1: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

file: ClippingMatrix.png
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

designation: clipping
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

bitmap 2: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

file: NervesCircuitMask.png
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

designation: nerves
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

bitmap 3: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

file: Wound.png
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

designation: wound
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

bitmap 4: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

file: CutLines.png
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

designation: cuts
\end_layout

\end_inset


\end_layout

\begin_layout Standard
For each bitmap, BETSE will look for a text block that gives the bitmap
 number, the file name, and a term called the 'designation'.
 The text blocks are formated as: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
bitmap 2: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

file: NervesCircuitMask.png
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

designation: nerves
\end_layout

\end_inset


\end_layout

\begin_layout Standard
and are templates, where one is needed for each bitmap you want to read
 in.
 This is one of two places in the config file where you are able to edit
 the text more aggressively.
 If you have more bitmaps than templates existing in your config file, you
 can simply copy and paste this block of text into the list of text blocks
 in order to include more bitmaps (just remember to increase the 'number
 of bitmaps' field to accurately reflect the number of bitmaps you're trying
 to read in, to update the numbering of the 'bitmap #' header, and to maintain
 the proper tabulation in the text formating of the config file).
 If you have less bitmaps than blocks, you can delete as many of these text
 blocks as you require.
 The order you list your bitmaps to be read in has no particular effect
 on the outcome.
 
\end_layout

\begin_layout Standard
The 'designation' field under each profile gives BETSE extra information
 about how the bitmap will be used to shape your cluster geometry or define
 tissue profiles.
 You have four options that can be used as a designation:
\end_layout

\begin_layout Itemize
clipping
\begin_inset space \qquad{}
\end_inset

 
\emph on
you want this bitmap to define the overall shape of your cluster
\end_layout

\begin_layout Itemize
cavity 
\begin_inset space \qquad{}
\end_inset

 
\emph on
you want this bitmap to cut a hole in the model at the time of world seeding
\end_layout

\begin_layout Itemize
cuts 
\begin_inset space \qquad{}
\end_inset

 
\emph on
you want this bitmap to define regions that are amputated in a simulation
 run
\end_layout

\begin_layout Itemize
profile name
\begin_inset space \qquad{}
\end_inset

 
\emph on
this bitmap is used to define a tissue profile also called 'profile name'
 (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Tissue-Profiles"

\end_inset

)
\end_layout

\begin_layout Subsection
Tissue Profiles
\begin_inset CommandInset label
LatexCommand label
name "sub:Tissue-Profiles"

\end_inset


\end_layout

\begin_layout Standard
After specifying if and how bitmaps should be used in your simulation, go
 on to define tissue profiles.
 
\end_layout

\begin_layout Standard
Each simulation has a 'default tissue', which represents all cells that
 aren't assigned to any tissue profiles.
 For plotting purposes, you can give this default tissue a name:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
default tissue name: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

normal_tissue
\end_layout

\end_inset


\end_layout

\begin_layout Standard
More importantly, you can specify the base membrane diffusion constants
 for cells in the 'default tissue'.
 All membrane diffusion constants are specified in units [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s].
 These membrane diffusion constants effectively set the resting V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 of these cells:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
base tissue properties:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_Na: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_K: 15.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_Cl: 2.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_Ca: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_H: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_M: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_P: 0.0
\end_layout

\end_inset


\end_layout

\begin_layout Standard
After setting the base membrane properties of the default tissue, go on
 to tell BETSE how many tissue profiles you'll be including in your cluster:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
number of tissue profiles: 4
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A sequence of text blocks follows the line declaring the number of tissue
 profiles (one text block for each desired tissue profile).
 The text blocks are all formated according to the following template:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
tissue profile 2:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

name: nerves
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

cell targets: 'bitmap'
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

designation: None
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

insular: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_Na: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_K: 15.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_Cl: 2.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_Ca: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_H: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_M: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

Dm_P: 0.0
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Each tissue profile must be given a unique name.
 If using bitmaps to define tissue profiles, the 'name' field of the tissue
 profile must correspond to the designation of the bitmap (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Using-Bitmaps-to"

\end_inset

).
 Also, in order to use bitmaps, use 'cell targets: bitmap' for the tissue
 profile using the bitmap.
 
\end_layout

\begin_layout Standard
It is also possible to define tissue profiles without using bitmap images.
 For this, you can:
\end_layout

\begin_layout Standard
specify the cells to be targeted using the plottable cell enumeration index
 of desired cells inside square brackets (just be careful that the cell
 index you type actually exists in your cluster else BETSE will crash):
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cell targets: [0,3,6]
\end_layout

\end_inset


\end_layout

\begin_layout Standard
target all cells in the population by typing:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cell targets: all
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Randomly select a proportion of the cell population to be targets by typing
 the word 'random' immediately followed by an integer from 1 to 100.
 For instance, to randomly target 47% of the cell population type:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cell targets: random47
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 'designation' of each tissue profile allows you to mark this profile
 as a 'cavity' (where cells are removed at the time of world seeding and
 prior to an initialization) or as 'cuts' (where cells are removed after
 world seeding and after an initialization at the beginning of a simulation
 run).
 There are three options for the tissue profile's 'designation':
\end_layout

\begin_layout Itemize
None
\begin_inset space \qquad{}
\end_inset


\emph on
 do nothing special, treat as a regular tissue profile
\end_layout

\begin_layout Itemize
cavity
\begin_inset space \qquad{}
\end_inset


\emph on
 remove this geometry at the time of world building
\end_layout

\begin_layout Itemize
cuts 
\begin_inset space \qquad{}
\end_inset

 
\emph on
mark this geometry to be removed under a targeted intervention cutting event
 at the start of a sim run
\end_layout

\begin_layout Standard
The 'insular' field of a tissue profile block indicates whether you want
 this tissue profile's cells to be connected to all other tissue profile
 cells via gap junctions (insular: False), or whether you want the tissue
 profile's cells to remain gap junction separated from cells in other profiles
 (insular: True).
\end_layout

\begin_layout Standard
The list of 'Dm Na', 'Dm K', etc, allows you to set individual membrane
 diffusion constants (in units m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s) of all ions included in your simulation for the cells of a particular
 tissue profile.
 This essentially controls the resting V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 of cells in the tissue profile.
 
\end_layout

\begin_layout Standard
The order of the 'tissue profile' text blocks is important, as each profile
 is laid over the next.
 Properties that cannot be shared between two profiles (such as membrane
 permeability) are overridden by higher-number profiles over lower number
 profiles.
 For example, if a group of cells is present in tissue profile 1 and tissue
 profile 2, the membrane diffusion constants of cells in both profiles would
 be set to those of tissue profile 2.
 
\end_layout

\begin_layout Subsection
Boundary Profiles
\end_layout

\begin_layout Standard
Boundary profiles apply only to full environmental simulations (i.e.
 where 'simulate ECM' is True) and are specifications of the left (L), right
 (R), top (T) or bottom (B) boundaries of the global environment (which
 is a square box around your cluster), to which an external voltage can
 be applied in 
\emph on
Targeted Interventions
\emph default
.
 
\end_layout

\begin_layout Standard
Each boundary profile is to be given a name, and the boundary target (L,
 R, T, or B) specified.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
number of boundary profiles: 2
\end_layout

\begin_layout Plain Layout

\family typewriter
boundary profile 1: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

name: '+V'
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

boundary targets: T
\end_layout

\begin_layout Plain Layout

\family typewriter
boundary profile 2: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

name: '-V'
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

boundary targets: B
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In this section you can also specify whether the global boundaries are closed
 ('closed boundary: True'), in which case there is no exchange of any reagent
 outside of the bounding box, or whether the global boundaries are open
 ('closed boundary: False'), in which case the global boundaries are assumed
 connected to a large environmental sink.
 Note if boundaries are closed it's not possible to introduce different
 concentrations of ions or morphogen as outlined in 
\emph on
Global Interventions
\emph default
.
 
\end_layout

\begin_layout Section
Targeted Interventions
\begin_inset CommandInset label
LatexCommand label
name "sec:Scheduled-Interventions"

\end_inset


\end_layout

\begin_layout Subsection
How to Use Targeted Interventions
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configTargetedInterven.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
Targeted Interventions
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-Scheduled-Interventions"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard

\emph on
Targeted Interventions
\emph default
 allow you to alter key simulation variables, such as specific membrane
 permeability, in a time-dependent manner, where changes are applied to
 specific tissue profiles.
 The following types of targeted interventions are available in BETSE 0.2:
\end_layout

\begin_layout Itemize
Temporarily change membrane permeability to Na
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Temporarily change membrane permeability to K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Temporarily change membrane permeability to Cl
\begin_inset script superscript

\begin_layout Plain Layout
-
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Temporarily change membrane permeability to Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset


\end_layout

\begin_layout Itemize
Temporarily produce IP
\begin_inset script subscript

\begin_layout Plain Layout
3
\end_layout

\end_inset


\begin_inset script superscript

\begin_layout Plain Layout
-3
\end_layout

\end_inset

 (inositol triphosphate)
\end_layout

\begin_layout Itemize
Temporarily apply an external voltage to global environmental boundaries
 (requires simulate ECM = True)
\end_layout

\begin_layout Itemize
Break extracellular matrix junctions (requires simulate ECM = True)
\end_layout

\begin_layout Itemize
Cut a piece out of the cluster 
\end_layout

\begin_layout Standard
In contrast to globally scheduled changes, 
\emph on
targeted interventions
\emph default
 are associated with a tissue profile, and can therefore be applied to specific
 regions of your model and not others.
\end_layout

\begin_layout Standard
Most targeted interventions follow a similar general format:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status collapsed

\begin_layout Plain Layout

\family typewriter
change Na mem:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

event happens: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change start: 5 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change finish: 10 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change rate: 1 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

multiplier: 10
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

function: gradient_x
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

apply to: ['nerves','wound']
\end_layout

\end_inset


\end_layout

\begin_layout Standard
By setting 'event happens' to True, you indicate that this targeted intervention
 will apply in your simulation run.
 The fields 'change start', 'change finish' and 'change rate' indicate the
 simulation time, in seconds, at which the interventions starts, finishes,
 and the rate at which the influence goes from none to all.
 The field 'multiplier' will multiply the base level of the variable by
 the specified amount.
 
\end_layout

\begin_layout Standard
The field 'function' allows you to let the intervention be further modified
 by a linear function, where your options are: 'None' (use no function),
 'gradient_x' (to create a gradient in the parameter along the horizontal
 axis), 'gradient_y' (to create a gradient in the vertical direction), and
 'gradient_r' (to create a radial gradient).
 If a gradient function is used, the targeted intervention magnitude will
 vary smoothly from zero (no effect) to the value specified by the 'multiplier'
 field along the direction of the gradient.
 Function properties, including the slope and offset of the gradients, can
 be specified a little further down in the configuration file under the
 'function properties' fields.
 
\end_layout

\begin_layout Standard
Finally, use the 'apply to' field to specify how the targeted intervention
 applies to your cell population.
 This must be specified as a tissue profile name, or a sequence of names,
 using the text formatting shown in the example (square brackets with tissue
 profile names in quotes and separated by commas if there are more than
 one).
 
\end_layout

\begin_layout Subsection
Applying an external voltage
\end_layout

\begin_layout Standard
Applying external voltage is a unique kind of targeted intervention for
 which it's worth mentioning a few points.
\end_layout

\begin_layout Standard
In order to apply an external voltage to your model, you must be simulating
 a full environment ( 'simulate ECM: True' under 
\emph on
General Options
\emph default
 section of the config file) and you must have two boundary profiles defined
 (these are found at the end of the 
\emph on
Tissue Designation 
\emph default
section of the config file).
 The text-block defining the 'apply external voltage' intervention is similar
 to other targeted interventions, however, the 'peak value' field represents
 the voltage (units Volts) that will be applied to each of the two boundaries.
 The 'apply to' field requires the name of two boundary profiles to be specified
: first the name of the boundary profile for which a positive voltage will
 be applied, then specify the name of the boundary profile for which a negative
 voltage will be applied.
 You must specify two and only two boundary profiles.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
apply external voltage:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

event happens: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change start: 5 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change finish: 10 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

change rate: 1 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

peak value: 0.5
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

apply to: ['name_of_pos_v_bound_profile','name_of_neg_v_bound_profile']
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Cutting events
\end_layout

\begin_layout Standard
Cutting events are a unique kind of targeted intervention for which it's
 worth mentioning a few additional points.
 In order for cutting events to work, you must have a tissue profile with
 a designation of 'cuts' defined for your simulation (see section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Tissue-Profiles"

\end_inset

).
 Cutting events can only be applied to one tissue profile, so the 'apply
 to' field will always be square brackets with one profile name listed.
 
\end_layout

\begin_layout Standard
The cutting event happens at the very beginning of a simulation run, so
 there are no time-specific settings for this type of targeted intervention.
 
\end_layout

\begin_layout Standard
The cutting event also has the features of 'damaged membranes', which controls
 whether cells immediately adjacent to removed cells develop damaged (and
 therefore leaky) membranes.
 Set this field to True to implement damaged membranes after cutting.
 
\end_layout

\begin_layout Standard
The field 'hurt level' indicates the amount of damage to be incorporated,
 and is a multiplier of the free diffusion constants.
 Typically, cell membrane diffusion coefficients are 1e-9 times smaller
 than the free diffusion coefficients.
 Therefore, a 'hurt level' of 1e-6, applied to all ions, represents a significan
t leak of membranes.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
cutting event:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

event happens: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

apply to: ['wound']
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

damaged membranes: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

hurt level: 1e-6
\end_layout

\end_inset


\end_layout

\begin_layout Section
Dynamic Ion Channels
\begin_inset CommandInset label
LatexCommand label
name "sec:Dynamic-Ion-Channels"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configDynChan.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
Dynamic Ion Channels
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-Dynamic-Ion"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
Dynamic channels represent changes to membrane permeability that are in
 relation to values of simulation variables, such as the V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 or the level of cytosolic Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 in a cell, rather than being forced changes that are scheduled by the user.
 
\end_layout

\begin_layout Subsection
Gated Ion Channels
\end_layout

\begin_layout Standard
Gated ion channels are membrane permeabilities responding to the computed
 values of variables in the simulation (such as levels of Vmem or calcium).
 If you decide to use gated channels, they are always present on the cells
 that you ascribe them to, however, the gated channels will only become
 active if the simulation parameters they respond to fall into appropriate
 ranges during the simulation.
\end_layout

\begin_layout Standard
Different kinds of dynamic ion channels can be included:
\end_layout

\begin_layout Itemize
voltage gated sodium channels
\end_layout

\begin_layout Itemize
voltage gated potassium channels 
\end_layout

\begin_layout Itemize
voltage gated calcium channels
\end_layout

\begin_layout Itemize
calcium gated potassium channels
\end_layout

\begin_layout Itemize
calcium dynamics (endoplasmic reticulum stores with inositol triphosphate
 and calcium induced-calcium releases) 
\end_layout

\begin_layout Standard
The 
\emph on
Dynamic Ion Channels
\emph default
 section of the config file doesn't make many options for the dynamics of
 these channels available, however, if you want to alter their behavior
 see the 
\emph on
Internal Use Only
\emph default
 section of the config file and section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Editing-Internal-Parameters"

\end_inset

 of this documentation.
 
\end_layout

\begin_layout Standard
Including dynamic channels in your simulation is simple: simply set the
 'turn on' field under the desired channel to 'True' and indicate which
 tissue profile(s) the dynamic channel is present on by using the 'apply
 to' field.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
voltage gated Na+: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

turn on: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

apply to: ['nerves']
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The actual dynamic variables that control the specific behavior of any included
 gated channels are listed in the 
\emph on
Internal Use Only
\emph default
 section of the configuration file, see 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Editing-Internal-Parameters"

\end_inset


\end_layout

\begin_layout Subsection
Calcium Dynamics
\end_layout

\begin_layout Standard
If the 'turn on' field under 'calcium dynamics' is set to True, an endoplasmic
 reticulum (ER) space is created within each cell.
 This ER space has its own Ca-ATPase pump, which pumps Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 from the cytoplasm and into the ER, maintaining an intracellular store
 of Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

in the organelle.
 The ER also has a semi-permeable membrane and a voltage across the ER membrane.
 The ER membrane is further fitted with inositol-triphosphate (IP3) receptors,
 which can respond to levels of cytosolic IP3 and Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 and open to let the stored ER's Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 rush out to the cytoplasm.
 Finally, with calcium dynamics enabled, IP3 is included in the simulation
 as a variable and can be produced in cells by using a targeted intervention.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
Ca dynamics: 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

turn on: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

apply to: ['tissue']
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

include:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset


\begin_inset space \qquad{}
\end_inset

calcium regulation: False
\end_layout

\end_inset


\end_layout

\begin_layout Standard
By setting the 'Ca dynamics' to True, you are simply adding in the ER space,
 Ca-ATPase pump on the ER, and ability to produce and electrodiffuse IP3.
 If 'calcium regulation' field is set to True, the calcium channels of the
 ER will be co-regulated by intracellular Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

, a phenomenon known as calcium-induced-calcium-release (CICR).
 
\end_layout

\begin_layout Standard
Note that if you are using an ion profile that does not include Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 ions, all of the calcium dynamics features will be ignored.
 Ion profiles that include calcium are 'basic_Ca' and 'animal'.
 
\end_layout

\begin_layout Section
Results Output and Visualization
\begin_inset CommandInset label
LatexCommand label
name "sec:Results-Output-and"

\end_inset


\end_layout

\begin_layout Standard
The 
\emph on
Results
\emph default
 section of the configuration file (Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-Results-section"

\end_inset

) allows you to specify what kind of plots, animations and raw data exports
 you want, whether you want to automatically save images, and where you
 want to save all of this information on your computer.
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Screenshot_configResults.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The 
\emph on
Results
\emph default
 section of a BETSE configuration file.
\begin_inset CommandInset label
LatexCommand label
name "fig:The-Results-section"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
Here we'll step through and explain features listed under the 'results options'
 header.
\end_layout

\begin_layout Standard
The 'turn all plots off' option allows you to turn all plots on (if False)
 or off (if True).
 Note that this feature doesn't turn the 'plot while solving' image off
 if it's selected (see below).
 This feature does turn off the animations.
 It is intended to be a way to prevent any visual output from appearing
 after an initialization (init) or simulation (sim) has completed.
 Note that 'turn all plots off' is enabled by default, so to create plotted
 output automatically after a seed, prep, or run, you must turn this setting
 to False:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
turn all plots off: False
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The 'plot while solving' option allows you to specify whether you wish to
 show a continuously updating 2d plot of cell V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 while the init or sim is actively computing.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
plot while solving: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you want to save the 'plot while solving' image, simply set the 'save
 solving plot' field to True.
 This will create a new folder called 'solving plot' in the results directory,
 which will be filled with 300 dpi png image frames saved from the simulation.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
save solving plot: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
BETSE simulations can produce a lot of graphical output.
 To automatically save all plots to the results directory as 300 dpi png
 images, simply set the 'automatically save plots' field to True.
 Appropriately labeled images will appear in the results directory folder
 after a successful simulation completes.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
automatically save plots: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To turn all animations on, simply set the 'create all animations' field
 to True.
 If False, no animations are created.
 This setting is intended to be an easy way to toggle animations on or off:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
create all animations: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you want to save animations, set the 'save animations' field to True.
 If True, each frame of an animation played at the end of a simulation will
 be saved to a 96 dpi png in its own folder in the animation folder inside
 the results directory.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
save animations: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you wish to export all time-specific data for a single cell (the export
 will apply to the cell index specified by the field 'plot cell index',
 see below) to a comma delimited text file (.csv) that can be imported into
 a spreadsheet program, set the 'export data to file' field to True.
 This will export all stored data (all ion concentrations, voltages, at
 all sampled times) for the 'plot cell index' cell (see below) to a csv
 file.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
export data to file: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In BETSE, each cell is indexed by a number.
 Every time an initialization is run and a new world created, the numbering
 scheme changes.
 To see what number corresponds to what cell in the cluster, set the 'enumerate
 cells' field to True.
 In the absence of an interactive GUI, this can help you decide which cell
 you are interested in getting specific data on (for single cell graphs
 plotted over time) or to target with a scheduled intervention.
 A warning that 'enumerate cells' should not be used for world sizes over
 200 um as there are far too many cells to resolve the numbers.
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
enumerate cells: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/vm_54_Enumerate_True
	lyxscale 50
	width 60text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The enumerate cells option puts the cell index on the plot so you can identify
 individual cells.
 
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
To tell BETSE what cell you're interesting in plotting (single cell graphs)
 and exporting single-cell data, specify a cell index in the 'plot cell
 index' field (note this must be an integer).
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
plot cell index: 5
\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you want to plot time-specific data for a single cell (the one specified
 in the 'plot cell index' field) set the 'plot single cell graphs' field
 to True.
 This will generate a set of graphs of data relevant to your simulation.
 An example of a single cell graph is shown in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:singlecellgraph"

\end_inset

.
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
plot single cell graphs: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/fig_Vmem_time
	lyxscale 20
	width 60text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
An example of cell Vmem plotted for cell index 5 in the cluster
\begin_inset CommandInset label
LatexCommand label
name "fig:singlecellgraph"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
BETSE allows you to have two main ways to display your 2D data: you can
 represent it as a color-value with each cell drawn as a discrete object
 (Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:showcells"

\end_inset

, left) or you can interpolate the data value from the center of each cell
 and produce a smoothed representation (Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:showcells"

\end_inset

, right).
 The interpolated option is particularly convenient (and faster to plot)
 for large cluster sizes (> 500 um) with many thousand cells.
 To plot discrete cells set the 'show cells' field to True, to plot interpolated
 data surfaces set this field to False.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
show cells: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/vm_82_ShowCellsOnOffFigure.png
	lyxscale 50
	width 100text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
An example of 'show cells' being True (left image) versus False (right image)
\begin_inset CommandInset label
LatexCommand label
name "fig:showcells"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
If you wish to create a streamline plot of currents as an overlay on all
 of your plots and animations, choose the: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
overlay currents: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Set the density of streamlines shown in these overlays using the option:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
streamline density: 2.0
\end_layout

\end_inset


\end_layout

\begin_layout Standard
And if simulating a full environment, specify whether you want extracellular
 current (True) or intracellular current (False) to be plotted:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
plot extracellular I: True
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Depending on what optional elements (
\emph on
General Options
\emph default
) and dynamics (
\emph on
Dynamic Channels
\emph default
) you've selected for a simulation, there are a number of different data
 variables you can plot: 
\end_layout

\begin_layout Itemize
Vmem 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot the transmembrane voltage for the 2D cluster of cells
\end_layout

\begin_layout Itemize
Ca 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot intracellular calcium levels for the 2D cluster of cells (if calcium
 included in the ion profile)
\end_layout

\begin_layout Itemize
IP3 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot intracellular IP3 levels for the 2D cluster of cells (if calcium included
 in the ion profile and calcium dynamics is True)
\end_layout

\begin_layout Itemize
Morpho 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot levels of morphogen for the 2D cluster of cells (if morphogen is included).
 If simulating a full environment will plot intra and extracellular levels
\end_layout

\begin_layout Itemize
Vcell 2D
\begin_inset space \qquad{}
\end_inset


\emph on
if simulating a full environment, plot the voltage inside each cell and
 optionally the environmental voltage
\end_layout

\begin_layout Itemize
Efield 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot the electric field in the cluster for the 2D map of cells 
\end_layout

\begin_layout Itemize
Currents 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot ionic currents in the cluster
\end_layout

\begin_layout Itemize
Pressure 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot pressure in the cluster (if electroosmosis is simulated)
\end_layout

\begin_layout Itemize
Velocity 2D
\begin_inset space \qquad{}
\end_inset


\emph on
plot fluid velocity in the cluster (if electroosmosis is simulated)
\end_layout

\begin_layout Itemize
Vmem Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate the transmembrane voltage for the 2D map of cells
\end_layout

\begin_layout Itemize
Ca Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate intracellular calcium levels for the 2D cluster of cells (if calcium
 included in the ion profile)
\end_layout

\begin_layout Itemize
IP3 Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate intracellular IP3 levels for the 2D cluster of cells (if calcium
 included in the ion profile and calcium dynamics is True)
\end_layout

\begin_layout Itemize
Morpho Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate levels of morphogen for the 2D cluster of cells (if morphogen is
 included).
 If simulating a full environment will plot intra and extracellular levels
\end_layout

\begin_layout Itemize
Vmem GJ Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate the intracellular voltage for the 2D cluster of cells with gap junction
 open-close state superimposed on top
\end_layout

\begin_layout Itemize
Vcell Ani
\begin_inset space \qquad{}
\end_inset


\emph on
if simulating a full environment, animate the voltage inside the cell 
\end_layout

\begin_layout Itemize
Current Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate ionic currents
\end_layout

\begin_layout Itemize
Efield Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate electric fields
\end_layout

\begin_layout Itemize
Velocity Ani
\begin_inset space \qquad{}
\end_inset


\emph on
animate electroosmostic fluid velocity (if electroosmosis included)
\end_layout

\begin_layout Standard
In the case that electroosmotic movement of ion pumps and channels has been
 enabled, a plot showing the final distribution of pumps and channels will
 automatically appear after the initialization (init) or simulation (sim).
 
\end_layout

\begin_layout Standard
Also, when creating or loading a world using the seed or plot seed commands,
 automatically generated plots showing the cluster's tissue profiles, gap
 junction connectivity, and environmental diffusion constant weighting (if
 simulating a full environment) appear.
 
\end_layout

\begin_layout Standard
Note that if you set a plot element, such as 'animate Ca2+' to true while
 you're using an ion profile that doesn't have Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 ions included, this plot or animation will simply be ignored.
 
\end_layout

\begin_layout Standard
Each plot or animation has settings allowing you to specify whether the
 plot appears (plot Vmem: True), if the color legend representing data values
 should be automatically scaled to the minimum and maximum values of the
 data set obtained in the simulation ('autoscale colorbar: True') or if
 you would like to supply your own minimum and maximum color legend limits
 ('autoscale colorbar: False').
 State the desired maximum and minimum values in the subsequent fields for
 the plot of interest: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
Vmem 2D:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

plot Vmem: True
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

autoscale colorbar: False 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

max val: 80.0
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

min val: -80.0 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
To get more control over the appearance of your plots you can change the
 colormap.
 A wide variety of colormaps are available to you, please see the Appendix
 (section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Appendix"

\end_inset

), subsection 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Available-Colormaps"

\end_inset

 for all of the options.
 The 'default colormap' field specifies the colormap used to plot cell-specific
 data.
 The 'gj colormap' is the one used to color gap junctions connecting cells.
 To change the default or gj colormap, simply type in the name of one of
 the available colormaps (it is case-sensitive and must be written exactly
 as displayed in the examples) into the 'default colormap' or 'gj colormap'
 field of the configuration file.
 To reverse the color-scheme, simply add on a '_r' to the end of the colormap
 name.
 If you misspell a colormap, BETSE will crash with an appropriate error
 message.
 
\end_layout

\begin_layout Standard
Using the 'rainbow' colormap: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
default colormap: rainbow
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Reversing the 'Blues' colormap by adding a '_r' to the end:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
gj colormap: Blues_r
\end_layout

\end_inset


\end_layout

\begin_layout Standard
It should be noted that there is a quirk to the color-bar scale, which appears
 whenever there is very little variation between elements of the 2D image
 (see Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Color-bar-rescales-to"

\end_inset

).
 To get rid of this effect, please set the 'autoscale colorbar' field of
 the figure to False.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/Confusing_scalebar_example.png
	lyxscale 80
	width 80text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Color-bar rescales to confusing units when there is very little variation
 between elements of the 2D map.
\begin_inset CommandInset label
LatexCommand label
name "fig:Color-bar-rescales-to"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Section
Editing Internal Parameters
\begin_inset CommandInset label
LatexCommand label
name "sec:Editing-Internal-Parameters"

\end_inset


\end_layout

\begin_layout Standard
A time-consuming aspect of BETSE development has been the identification
 of parameter values that are bio-realistic, and that produce stable and
 realistic results.
 The parameters listed under the 
\emph on
Internal Use Only
\emph default
 section of the configuration file are either well-known reference values
 (e.g.
 the free diffusion constants of ions in aqueous media) or the result of
 many hours of trial-and-error during development.
 Therefore, while altering these parameters may be exactly what you need
 to do to produce realistic output, keep in mind that doing so may create
 simulation instability (with ensuing BETSE crashes and error messages)
 or non-realistic output.
 
\end_layout

\begin_layout Standard
The first region of the 
\emph on
Internal Use Only
\emph default
 section concerns 'gated ion channel options', where you'll find settings
 to alter the dynamics of vgNa, vgK, voltage gated Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 (vgCa) and Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 gated K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 channels (cagK).
 Each channel works in a slightly different way.
 
\end_layout

\begin_layout Standard
The behavior of vgNa is based on three states constituting an active (open)
 state, inactive (refractory) state, and deactivated (closed) state.
 For vgNa, 'max Dmem Na' specifies the maximum cell membrane permeability
 to Na+ when the channel is in a fully open state [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s].
 The 'activation v' specifies the voltage above which vgNa is triggered
 to open [V].
 The 'inactivation v' [V] specifies the high voltage at which the vgNa is
 temporarily inactivated if the cell passes above the inactivation voltage.
 The 'deactivation v' [V] specifies the voltage, below which the vgNa is
 deactivated and requires another depolarization below the activated voltage
 to fire again.
 The 'live time' field [s] represents the maximum amount of time that the
 vgNa can remain active (under any circumstance) before becoming inactive
 and the 'dead time' field [s] specifies how long an inactivated channel
 remains unable to fire.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
voltage gated Na:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

max Dmem Na: 1e-15 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

activation v: -50e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

inactivation v: 30e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

deactivation v: -52e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

live time: 5e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

dead time: 10e-3 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The behavior of vgK is based on an active (open) state and a deactivated
 (closed) state.
 For vgK, 'max Dmem K' specifies the maximum cell membrane permeability
 to K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 when the channel is in a fully open state [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s].
 The 'activation v' specifies the voltage above which vgK is triggered to
 open [V].
 The 'deactivation v' [V] specifies the voltage, below which the vgK is
 deactivated and requires another depolarization below the activated voltage
 to fire again.
 The 'live time' field [s] represents the maximum amount of time that the
 vgK can remain active (under any circumstance) before becoming deactivated.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
voltage gated K:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

max Dmem K: 5e-16 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

activation v: -20e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

deactivation v: -70e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

live time: 10e-3 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The behavior of vgCa is based on an active (open) state and a deactivated
 (closed) state, however, vgCa states are determined by both V
\begin_inset script subscript

\begin_layout Plain Layout
mem
\end_layout

\end_inset

 and cytosolic Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 levels.
 For vgCa, 'max Dmem Ca' specifies the maximum cell membrane permeability
 to Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 when the channel is in a fully open state [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s].
 The 'activation v' specifies the voltage above which vgCa is triggered
 to open [V].
 The 'deactivation v' [V] specifies the voltage, above which the vgCa is
 deactivated and requires another depolarization across the activation voltage
 threshold to fire again.
 The 'inactivation Ca' field specifies the level of cytosolic Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 at which the vgCa deactivates, while the 'reactivation Ca' field specifies
 the cytosolic Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 level when the vgCa can become active again.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
voltage gated Ca:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

max Dmem Ca: 1.0e-15 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

activation v: -40e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

inactivation v: 40e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

inactivation Ca: 1.0e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

reactivation Ca: 200e-6 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Calcium gated potassium channels (cagK) are based on an active (open) state
 and a deactivated (closed) state that is fully determined by cytosolic
 Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 levels.
 For cagK, 'max Dmem K' specifies the maximum cell membrane permeability
 to K
\begin_inset script superscript

\begin_layout Plain Layout
+
\end_layout

\end_inset

 when the channel is in a fully open state [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s].
 cagK channels are controlled by a Hill function to cytosolic Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 levels (for information about Hill functions please see 
\begin_inset CommandInset href
LatexCommand href
target "https://en.wikipedia.org/wiki/Hill_equation_%28biochemistry%29"

\end_inset

).
 The 'hill K_half' field specifies the K_half parameter of the Hill function
 (in mmol/L of cytosolic Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

), while the 'hill n' specifies the Hill coefficient of the equation.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
calcium gated K:
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

max Dmem K: 5.0e-16 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

hill K_half: 7.5e-4 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset space \qquad{}
\end_inset

hill n: 3
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Calcium dynamics are controlled by fields under the 'calcium dynamics parameters
' header.
 
\end_layout

\begin_layout Standard
The first few settings relate to release of Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 from the ER.
\end_layout

\begin_layout Standard
The ER IP3-receptors have been shown to release Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 in a manner that is sensitive to how full the ER is with Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

.
 Higher concentrations of IP3 make the ER release Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 at lower levels of Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 storage.
 This leads to a modulation of the frequency of intracellular Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 oscillations with different concentrations of IP3.
 To turn this effect on in BETSE, set the 'IP3 frequency modulation level'
 to a value above 0.0, and below 0.9.
 The field 'ER max' stipulates the maximum membrane Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 diffusion coefficient of the ER when the IP3-receptor is open [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s].
 The fields 'ER burst' and 'ER close' give the levels of Ca
\begin_inset script superscript

\begin_layout Plain Layout
2+
\end_layout

\end_inset

 storage in the ER at which the ER IP3-receptor opens and closes (in the
 presence of IP3).
 The sensitivity of the ER IP3-receptor is controlled by a Hill function
 to cytosolic IP3 concentration.
 Set the 
\emph on
K
\begin_inset script subscript

\begin_layout Plain Layout
1/2
\end_layout

\end_inset


\emph default
 coefficient and the Hill 
\emph on
n
\emph default
 coefficient for this curve using the 'IP3 K half' and 'IP3 hill n' fields.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
IP3 frequency modulation level: 0.8
\end_layout

\begin_layout Plain Layout

\family typewriter
ER max: 5.0e-15
\end_layout

\begin_layout Plain Layout

\family typewriter
ER burst: 0.8
\end_layout

\begin_layout Plain Layout

\family typewriter
ER close: 0.5
\end_layout

\begin_layout Plain Layout

\family typewriter
IP3 K half: 1e-3
\end_layout

\begin_layout Plain Layout

\family typewriter
IP3 hill n: 3.4
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The ER's IP3-receptors are also sensitive to cytosolic calcium levels, which
 is called calcium-induced-calcium-release (CICR).
 In BETSE, the Ca2+ sensitivity of the IP3-receptor is controlled by a Gaussian
 curve.
 Use the 'CICR Ca peak' and 'CICR Ca width' fields to modify the cytosolic
 calcium level midpoint and spread, respectively [mmol/L or mol/m
\begin_inset script superscript

\begin_layout Plain Layout
3
\end_layout

\end_inset

].
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
CICR Ca peak: 500.0e-6
\end_layout

\begin_layout Plain Layout

\family typewriter
CICR Ca width: 80.0e-6
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A cell's ER typically occupies 10% of the cell's volume, and has a surface
 area up to 10x the outer surface area of the cell.
 Use the fields 'ER_vol' and 'ER_sa' to specify the volume and surface area
 of the ER, as a fraction of the cell's volume and surface area, respectively.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
ER_vol: 0.1
\end_layout

\begin_layout Plain Layout

\family typewriter
ER_sa: 1.0 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Inositol-tri-phosphate (IP3) is an important signaling molecule, especially
 important in calcium dynamics.
 Set the membrane and gap junction diffusion coefficients [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s], charge state, and initial concentrations of IP3 in cells and the environmen
t [mmol/L or mol/m
\begin_inset script superscript

\begin_layout Plain Layout
3
\end_layout

\end_inset

] using the following fields: 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
Dm_IP3: 1.0e-18
\end_layout

\begin_layout Plain Layout

\family typewriter
Do_IP3: 1.0e-5
\end_layout

\begin_layout Plain Layout

\family typewriter
z_IP3: -3
\end_layout

\begin_layout Plain Layout

\family typewriter
cIP3_to: 1e-6
\end_layout

\begin_layout Plain Layout

\family typewriter
cIP3_to_env: 1e-6
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Under the 'internal parameters' header you can set the default free diffusion
 (gap junction diffusion) constants of the main ions [m
\begin_inset script superscript

\begin_layout Plain Layout
2
\end_layout

\end_inset

/s]:
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
Do_Na: 1.33e-9 
\end_layout

\begin_layout Plain Layout

\family typewriter
Do_K: 1.96e-9 
\end_layout

\begin_layout Plain Layout

\family typewriter
Do_Cl: 2.03e-9 
\end_layout

\begin_layout Plain Layout

\family typewriter
Do_Ca: 1.0e-9 
\end_layout

\begin_layout Plain Layout

\family typewriter
Do_H: 2.5e-9 
\end_layout

\begin_layout Plain Layout

\family typewriter
Do_M: 1.0e-9 
\end_layout

\begin_layout Plain Layout

\family typewriter
Do_P: 5.0e-10 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
You can also re-define parameters related to each of the ion pumps.
 For each pump, the 'alpha_*' term represents the rate constant of the pump
 in units [m/mol
\begin_inset space \thinspace{}
\end_inset

s].
 Each of the pumps is controlled by a logistic equation that uses the available
 free energy as the main parameter.
 The 'halfmax_*' and 'slope_*' fields determine the available free energy
 level (in KJ) at which the pump activity is halved, and the free energy
 spread around this half-max value, respectively.
 
\end_layout

\begin_layout Standard
\begin_inset Box Shaded
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout

\family typewriter
alpha_NaK: 5.0e-8 
\end_layout

\begin_layout Plain Layout

\family typewriter
halfmax_NaK: 12 
\end_layout

\begin_layout Plain Layout

\family typewriter
slope_NaK: 24 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset VSpace bigskip
\end_inset


\end_layout

\begin_layout Plain Layout

\family typewriter
alpha_Ca: 2.5e-5 
\end_layout

\begin_layout Plain Layout

\family typewriter
alpha_CaER: 2.5e-4 
\end_layout

\begin_layout Plain Layout

\family typewriter
halfmax_Ca: 12 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset VSpace bigskip
\end_inset


\end_layout

\begin_layout Plain Layout

\family typewriter
alpha_HK: 1.0e-3 
\end_layout

\begin_layout Plain Layout

\family typewriter
halfmax_HK: 12 
\end_layout

\begin_layout Plain Layout

\family typewriter
slope_HK: 24 
\end_layout

\begin_layout Plain Layout

\family typewriter
\begin_inset VSpace bigskip
\end_inset


\end_layout

\begin_layout Plain Layout

\family typewriter
alpha_V: 2.0e-4 
\end_layout

\begin_layout Plain Layout

\family typewriter
halfmax_V: 12 
\end_layout

\begin_layout Plain Layout

\family typewriter
slope_V: 24 
\end_layout

\end_inset


\end_layout

\begin_layout Standard

\end_layout

\begin_layout Section
Upcoming Features 
\begin_inset CommandInset label
LatexCommand label
name "sec:Upcomming-Features"

\end_inset


\end_layout

\begin_layout Itemize
Graphical user interface (GUI)
\end_layout

\begin_layout Itemize
Interactivity (e.g.
 select cells using mouse-clicks, dynamically change variables using slider-bars
, turn features on/off while in a simulation using buttons)
\end_layout

\begin_layout Itemize
Saving animations to *.mp4 video files
\end_layout

\begin_layout Itemize
Parallel processing to make use of multi-core CPUs and speed up simulations
\end_layout

\begin_layout Section
BETSE Theory
\begin_inset CommandInset label
LatexCommand label
name "sec:BETSE-Theory"

\end_inset


\end_layout

\begin_layout Subsection
Discretization of Differential Equations
\end_layout

\begin_layout Standard
It is common practice to discretize space and time in order to solve ordinary
 differential equations numerically.
\end_layout

\begin_layout Standard
Time can simply be discretized as a set of incrementally increasing values,
 indexed by '
\emph on
k
\emph default
'.
\end_layout

\begin_layout Standard
For some observable 
\begin_inset Formula $f$
\end_inset

, which depends on spatial coordinates x and y, and time t, first-order
 changes in time can be approximated as:
\end_layout

\begin_layout Standard
\begin_inset Formula $\frac{df(x,y,t)}{dt}\Rightarrow\frac{f(x,y,t_{k+1})-f(x,y,t_{k})}{\Delta t}=g(x,y)$
\end_inset


\end_layout

\begin_layout Standard
Therefore, if 
\begin_inset Formula $f(x,y,t_{k})$
\end_inset

 is known, the value at the next time increment can be solved for as:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
f(x,y,t_{k+1})=f(x,y,t_{k})+\Delta t\,g(x,y)
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
This is known as Euler's Method, and is how BETSE solvers update equations
 in time.
\end_layout

\begin_layout Standard
Space is discretized using grids of points.
 
\end_layout

\begin_layout Standard
Basic spatial derivatives can be calculated on discrete grids using Finite
 Difference formula.
 
\end_layout

\begin_layout Standard
First derivatives in space can be estimated using the central difference
 formula for a grid with uniform spacing 
\emph on
h
\emph default
 and points on the grid indexed by their i
\begin_inset script superscript

\begin_layout Plain Layout
th
\end_layout

\end_inset

 row and j
\begin_inset script superscript

\begin_layout Plain Layout
th
\end_layout

\end_inset

 column (see Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:CalculatingDerivatives"

\end_inset

):
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\frac{df(x_{j},y_{i})}{dx}\Rightarrow\frac{f(x_{j+1},y_{i})-f(x_{j-1},y_{i})}{2h}\label{eq:xderivative}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\frac{df(x,y)}{dy}\Rightarrow\frac{f(x_{j},y_{i+1})-f(x_{j},y_{i-1})}{2h}\label{eq:yderivative}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
These definitions of Equations 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:xderivative"

\end_inset

 and 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:yderivative"

\end_inset

 for first derivatives on a 2D grid are the building blocks for numerous
 discrete operators commonly used in differential equations, such as gradients,
 divergence and Laplacians (which we'll cover in the following sections).
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="2">
<features rotate="0" tabularvalignment="middle">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/MACsGrid_x_derivative.png
	lyxscale 20
	width 40text%

\end_inset


\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/MACsGrid_y_derivative.png
	lyxscale 20
	width 40text%

\end_inset


\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Calculating x- (left) and y- (right) spatial derivatives on a square grid
 with uniform spacing h.
\begin_inset CommandInset label
LatexCommand label
name "fig:CalculatingDerivatives"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Finite Volume Method
\begin_inset CommandInset label
LatexCommand label
name "sub:Finite-Volume-Method"

\end_inset


\end_layout

\begin_layout Standard
BETSE uses the Finite Volume Method (FVM) on structured grids to handle
 different kinds of phenomena described by ordinary differential equations.
 
\end_layout

\begin_layout Standard
The FVM works by expressing an ordinary differential equation in its integral
 form on a structured grid, which allows the Divergence Theorem to convert
 divergence operators into surface integrals.
 The Divergence Theorem states states that the outward flux of a vector
 field through a closed surface is equal to the volume integral of the divergenc
e over the region inside the surface, or in other words that the sum of
 all sources minus the sum of all sinks gives the net flow out of a region:
 
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\iiintop_{v}\nabla\cdot f(x,y)\,dv=\ointop_{s}\,f(x,y)\cdot\hat{n}_{s}ds\label{eq:gauss}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Equation 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:gauss"

\end_inset

 may look a bit messy, but we'll come back to hopefully see how it helps
 solve differential equations in a few lines.
 
\end_layout

\begin_layout Standard
Instead of having one grid of discrete points, the FVM splits space into
 an array of grid-cells, each having a center point (marked by 'x' in Figure
 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-MACs-Finite"

\end_inset

), and upper and lower boundaries with midpoints (the blue and green triangles
 of Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-MACs-Finite"

\end_inset

).
 This type of grid is sometimes referred to as a 
\begin_inset Quotes eld
\end_inset

marker and cell
\begin_inset Quotes erd
\end_inset

 or MACs grid, and is used to prevent unphysical oscillations in the solutions
 of linearized flow equations.
 The MACs grid-cells have a surface area at each grid-cell boundary (in
 2D this is simply a unit length equal to the spacing of the grid) and each
 grid-cell has a volume (in 2D this is the area of each grid-cell, equal
 to the spacing of the grid squared).
 The MACs grid helps to find discrete versions of operators such as gradients,
 divergence, and Laplacians.
 
\end_layout

\begin_layout Standard
Recall that by definition the gradient of a function is:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\nabla f(x,y)=\frac{df(x,y)}{dx}\hat{x}+\frac{df(x,y)}{dy}\hat{y}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
The use of the MACs grid has the advantage that if there is a scalar quantity
 
\begin_inset Formula $f(x,y)$
\end_inset

 defined on the grid (perhaps concentration of an ion, or a voltage) then
 Equations 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:xderivative"

\end_inset

 and 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:yderivative"

\end_inset

 can operate on the center points of the grid (again, these are marked by
 'x' in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-MACs-Finite"

\end_inset

) to yield a gradient of 
\begin_inset Formula $f(x,y)$
\end_inset

 with the x- component of the gradient defined on the 'u-grid' (the green
 triangles of Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-MACs-Finite"

\end_inset

) and y- component defined on the 'v-grid' (the blue triangles of Figure
 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-MACs-Finite"

\end_inset

).
 The components of the gradient of 
\begin_inset Formula $f(x,y)$
\end_inset

 that are normal to the surfaces of a unit grid-cell would appear on the
 MACs grid as shown in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Calculating-divergence-on"

\end_inset

.
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/MACsGrid_MACsBase.png
	lyxscale 30
	width 60text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The MACs Finite Volume Method grid with grid-cell centers ('x'), u-grid
 (green triangles pointing right), and v-grid (blue triangles pointing up).
 Indices of the i
\begin_inset script superscript

\begin_layout Plain Layout
th
\end_layout

\end_inset

 row and j
\begin_inset script superscript

\begin_layout Plain Layout
th
\end_layout

\end_inset

 column for grid-cell centers are shown.
 
\begin_inset CommandInset label
LatexCommand label
name "fig:The-MACs-Finite"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/MACsGrid_divergence.png
	lyxscale 30
	width 60text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Calculating divergence on a MACs grid involves using normal fluxes to the
 N, S, W and E surfaces of each grid-cell.
\begin_inset CommandInset label
LatexCommand label
name "fig:Calculating-divergence-on"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
An operator called the Laplacian, 
\begin_inset Formula $\nabla^{2}f(x,y)$
\end_inset

, shows up in several common differential equations (e.g.
 Poisson electrostatic equation).
 By definition the Laplacian is equal to:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\nabla^{2}f(x,y)=\frac{d^{2}f(x,y)}{dx^{2}}\hat{x}+\frac{d^{2}f(x,y)}{dy^{2}}\hat{y}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
However, the Laplacian can also be described as the divergence of the gradient
 of 
\begin_inset Formula $f(x,y)$
\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\nabla^{2}f(x,y)=\nabla\cdot\nabla f(x,y)
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
So that if we're doing the FVM method, we'd express a Laplacian as a volume
 integral, wherever it's appearing in the differential equation, and then
 go ahead and use the Divergence Theorem of Equation 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:gauss"

\end_inset

 on the resulting expression:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\iiiint_{v}\,\nabla^{2}f(x,y)\,dv=\iiiint_{v}\,\nabla\cdot\nabla f(x,y)\,dv=\ointop\,\nabla f(x,y)\cdot\hat{n_{s}\,ds}\label{eq:FVMandlaplacian}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Equation 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:FVMandlaplacian"

\end_inset

 may not look like much help yet, but on a grid it makes things really easy!
 It's saying that if we have a scalar quantity 
\begin_inset Formula $f(x,y)$
\end_inset

 defined on the grid-cell center points, we can first calculate the gradient
 using the discretized spatial derivatives of Equations 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:xderivative"

\end_inset

 and 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:yderivative"

\end_inset

.
 The resulting components of the gradient would be multiplied by the surface
 normals of the u-grid and v-grid unit vectors (directions given by the
 orientation of triangles in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Calculating-divergence-on"

\end_inset

).
 Finally, a Laplacian would be represented by the discrete surface integral
 of the multiplied components, which is given by the sum of the components
 of the gradient (see Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Calculating-divergence-on"

\end_inset

) times the grid side length 
\begin_inset Formula $h$
\end_inset

 (2D surface area equivalent dimension): 
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
(flux_{N}+flux_{S}+flux_{E}+flux_{W})\,h
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
If we were to work through the above-described math (i.e.
 use Equations 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:xderivative"

\end_inset

 and 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:yderivative"

\end_inset

 to obtain expressions for the gradients, multiply by grid-cell surface
 normal vectors, and then sum over the surface of a unit grid-cell), we
 would obtain the symbolic definition of the discrete Laplacian (note the
 multiplier 'h' varies depending on whether a FVM or Finite Difference method
 is being used, shown here is the FVM result):
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\nabla^{2}f(x,y)=\left(\frac{f_{i+1,j}-f_{ij}}{h}+\frac{f_{i-1,j}-f_{ij}}{h}+\frac{f_{i,j+1}-f_{ij}}{h}+\frac{f_{i,j-1}-f_{ij}}{h}\right)\,h\label{eq:discreteLaplacian}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Equation 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:discreteLaplacian"

\end_inset

 can be used to construct matrices (in BETSE called Poisson solvers), the
 inverse of which can be used to find the values of 
\begin_inset Formula $f(x,y)$
\end_inset

 upon which a Laplacian is abstractly acting (i.e.
 the inverse matrices can solve the Poisson or Laplace equations).
 
\end_layout

\begin_layout Standard
In the FVM, some functions must actually be integrated over the 'volume'
 of each grid-cell.
 This is done by interpolating the value of 
\begin_inset Formula $f(x,y)$
\end_inset

 at additional points of the grid (as shown in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:CalculatingIntegral"

\end_inset

), and calculating the integral using the equation:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\iiintop_{v}\,f(x,y)\,dv=\frac{h^{2}}{36}\,(16\,f_{O}+4\,f_{N}+4\,f_{S}+4\,f_{E}+4\,f_{W}+f_{SE}+f_{SW}+f_{NE}+f_{NW})
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Where 'O' is the central value of 
\begin_inset Formula $f(x,y)$
\end_inset

 and N, S, E, W, SE, SW, NE, and NW are the interpolated values of 
\begin_inset Formula $f(x,y)$
\end_inset

 in the cardinal directions, as shown in Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:CalculatingIntegral"

\end_inset

.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/MACsGrid_integral.png
	lyxscale 30
	width 60text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Calculating a spatial integral on any grid involves interpolating the function
 at to the N, S, W, E, NE, NW, SE and SW points of the grid-cell.
\begin_inset CommandInset label
LatexCommand label
name "fig:CalculatingIntegral"

\end_inset

 
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
When simulating a full environment, BETSE uses a square grid to compute
 environmental mass transports and other physical states, and a Voronoi
 grid for the cell transports and properties (see Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:The-Voronoi-grid"

\end_inset

).
 The square environmental grid interpolates points on the Voronoi grid to
 allow for coupling between cells and their environment (Figure 
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:InterpECMandCells"

\end_inset

).
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="1" columns="3">
<features rotate="0" tabularvalignment="middle">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top">
<column alignment="center" valignment="top">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/CellGrid_centres_mems_norms_clipped.png
	lyxscale 30
	width 28text%

\end_inset


\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/CellGrid_centres_mems_tang_clipped.png
	lyxscale 30
	width 30text%

\end_inset


\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/CellGrid_centres_gj_clipped.png
	lyxscale 30
	width 28text%

\end_inset


\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
The Voronoi grid used to calculate transport and other physical properties
 in and between biological cells has several types of structure.
 Center points (marked by blue squares) define the net location of cells
 and are analogous to the grid-cell center points of a standard Finite Volume
 method grid.
 Membrane midpoints with normal (far left image arrows) and tangent (middle
 image arrows) unit vector definition allow for directional gradients to
 be calculated for cells fluxing substances across their membrane (using
 membrane normals) and around the circumference of each cell (using membrane
 tangents) to be calculated.
 The far right image shows gap-junction tangent unit vectors, which connect
 the center points of two cells.
 
\begin_inset CommandInset label
LatexCommand label
name "fig:The-Voronoi-grid"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename BETSE_Math_and_Theory/FiggerFodder/MACsGrid_centres_uv_cells_mems_bounds_clipped.png
	lyxscale 50
	width 60text%

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Interpolation between regular square grid used for environmental regions
 (grid-cell centers marked by 'x') and the Voronoi grid representing cells
 (shown as a light blue shadow overlay).
 Red 'x' mark environmental regions identified as cluster outer boundaries,
 while green 'x' mark environmental regions identified as cells of the clusters.
 
\begin_inset CommandInset label
LatexCommand label
name "fig:InterpECMandCells"

\end_inset


\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Basic Bioelectric Modeling
\begin_inset CommandInset label
LatexCommand label
name "sub:Base-Bioelectric-Modeling"

\end_inset


\end_layout

\begin_layout Standard
Mass transport between gap-junction connected cells and environmental spaces
 (if simulating a full environment) was modeled using the full Nernst-Planck
 Equation: 
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\frac{dc(x,y,t)}{dt}=\nabla\cdot\left(-D(x,y,t)\,\nabla c(x,y,t)+\vec{u(x,y,t)}\,c(x,y,t)-\frac{D(x,y,t)\,z\,q}{k_{b}T}\,\nabla V(x,y,t)\right)\label{eq:NernstPlanck}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
with 
\begin_inset Formula $c(x,y,t)$
\end_inset

 being the concentration of a substance with spatially-varying diffusion
 constant 
\begin_inset Formula $D(x,y,t)$
\end_inset

, voltage 
\begin_inset Formula $V(x,y,t)$
\end_inset

 and optional electroosmotic fluid flow 
\begin_inset Formula $\vec{u(x,y,t)}$
\end_inset

.
 Equation 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:NernstPlanck"

\end_inset

 was represented in integral form and discretized so that it could be solved
 on BETSE's Voronoi cell grid or the MACs environmental grid (if simulating
 a full environment) using techniques described in section 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Finite-Volume-Method"

\end_inset

.
\end_layout

\begin_layout Standard
Net ionic charge, 
\begin_inset Formula $\rho_{e}$
\end_inset

, was calculated by summing concentrations of all ions, 
\begin_inset Formula $c_{i}$
\end_inset

, included in a particular simulation times their charge state, 
\begin_inset Formula $z_{i}$
\end_inset

, and the Faraday constant 
\begin_inset Formula $F$
\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\rho_{e}=\sum F\,z_{i}\,c_{i}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Voltages, 
\begin_inset Formula $V$
\end_inset

, were calculated from net ionic charge density using Poisson's electrostatic
 equation, where 
\begin_inset Formula $\varepsilon$
\end_inset

 represents the permittivity of the medium:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\nabla^{2}V=\frac{\rho_{e}}{\varepsilon}\label{eq:poisson}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Equation 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:poisson"

\end_inset

 was represented in integral form and solved using Poisson solver matrices
 using methods outlined in 
\begin_inset CommandInset ref
LatexCommand ref
reference "sub:Finite-Volume-Method"

\end_inset

.
\end_layout

\begin_layout Standard
The Goldman Flux Equation (this is NOT the same as the Goldman Equation
 or the GHK Equation) was used to calculate passive trans-membrane transport
 between the intra and extracellular environments across the thin cell membrane:
 
\end_layout

\begin_layout Subsection
Ion Pumps and Channels
\begin_inset CommandInset label
LatexCommand label
name "sub:Ion-Pumps-and"

\end_inset


\end_layout

\begin_layout Standard
Ion channels were modeled as dynamic alterations of membrane permeability
 to a specific ion.
 The dynamics of ion channels were rule based, responding to transmembrane
 voltage (
\begin_inset Formula $V_{mem}$
\end_inset

) or concentration of a gating ligand.
 
\end_layout

\begin_layout Standard
Active pumping of ions across cell membranes by ion pumps were modeled using
 simple rate equations, for example, the sodium flux of the NaK-ATPase pump,
 
\begin_inset Formula $f_{Na}$
\end_inset

, was calculated as:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
f_{Na}=-\alpha\,(cNa_{in})\,(cK_{out}^{(1/2)})
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Thermodynamic constraints were applied to ion pumping rates, 
\begin_inset Formula $\alpha$
\end_inset

, by calculating the free energy available to pump, 
\begin_inset Formula $\Delta G$
\end_inset

, and modifying the pump rate by a step equation as a function of the free
 energy available:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\Delta G_{Na}=R\,T\,ln(cNa_{out}/cNa_{in})-F\,V_{mem}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\Delta G_{K}=R\,T\,ln(cK_{in}/cK_{out})+F\,V_{mem}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\Delta G=\Delta G_{ATP}-(3\,\Delta G_{Na}+2\,\Delta G_{K})
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\alpha=\alpha_{o}\left(1/(1+exp(-\beta(\Delta G-\Delta G_{o})))\right)
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
Note 
\begin_inset Formula $\Delta G_{Na}$
\end_inset

 is the free energy required to pump one sodium ion out of the cell, 
\begin_inset Formula $\Delta G_{K}$
\end_inset

 is the free energy required to pump one potassium ion into the cell, and
 
\begin_inset Formula $\Delta G_{ATP}$
\end_inset

 is the free energy released with ATP hydrolysis to ADP.
 
\end_layout

\begin_layout Subsection
Electroosmosis
\begin_inset CommandInset label
LatexCommand label
name "sub:Electroosmosis"

\end_inset


\end_layout

\begin_layout Standard
Linearized Navier-Stokes equations for slow moving viscous flows were used
 to model fluid flow, where the vector fluid velocity was split into its
 x-component (
\begin_inset Formula $u$
\end_inset

) and y-component (
\begin_inset Formula $v$
\end_inset

), a body force 
\begin_inset Formula $F(x,y,t)$
\end_inset

 was present, and pressure was included as 
\begin_inset Formula $P$
\end_inset

:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\vec{u}=u\hat{x}+v\hat{y}
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\frac{du}{dt}=\nabla\cdot(\mu(x,y,t)\,\nabla u(x,y,t))+F(x,y,t)-\nabla P(x,y,t)
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
\frac{dv}{dt}=\nabla\cdot(\mu(x,y,t)\,\nabla v(x,y,t))+F(x,y,t)-\nabla P(x,y,t)
\end{equation}

\end_inset


\end_layout

\begin_layout Standard
For electroosmosis, a body force generated by an electric field acting on
 net charge was applied:
\end_layout

\begin_layout Standard
\begin_inset Formula 
\begin{equation}
F(x,y,t)=-\rho_{e}\nabla V
\end{equation}

\end_inset


\end_layout

\begin_layout Subsection
Lateral Movement of Pumps and Channels
\begin_inset CommandInset label
LatexCommand label
name "sub:Lateral-Movement-of"

\end_inset


\end_layout

\begin_layout Standard
Lateral movement of pumps and channels was modeled by using a density function,
 
\begin_inset Formula $\rho_{mem}$
\end_inset

, with conserved total amount on the cell membranes of each cell.
 
\begin_inset Formula $\rho_{mem}$
\end_inset

 was assumed to change via the Nernst-Planck Equation 
\begin_inset CommandInset ref
LatexCommand ref
reference "eq:NernstPlanck"

\end_inset

, for electric fields (
\begin_inset Formula $\nabla V$
\end_inset

) and flows (
\begin_inset Formula $\vec{u}$
\end_inset

) tangential to each membrane.
 
\end_layout

\begin_layout Section
About BETSE
\begin_inset CommandInset label
LatexCommand label
name "sec:About-BETSE"

\end_inset


\end_layout

\begin_layout Standard
BETSE was designed and developed by Alexis Pietak and Cecil Curry for the
 Levin Lab at Tuft's University.
 BETSE was also made as a tool to assist Alexis Pietak's theoretical exploration
s into the role of bioelectrical phenomenon in biological pattern formation.
\end_layout

\begin_layout Standard
Cecil (Brian) Curry is a software engineer and avid advocate and contributor
 to the open source software movement.
 Cecil is a computer science graduate of California Polytechnic State University
 in San Luis Obispo, and has worked as a software engineer/architect at
 
\emph on
Apple
\emph default
, on 
\emph on
Wall Street
\emph default
, and at a Silicon Valley start-up.
 Cecil has contributed invaluably to BETSE by identifying the suit of open-sourc
e tools used to facilitate BETSE development, by implementing the command
 line interface (and other system-level tools), and with his tireless pursuit
 of cross-platform portable BETSE executables.
 
\end_layout

\begin_layout Standard
Alexis Pietak is a multi-disciplinary scientist with training in physics,
 biochemistry, engineering, and biomedical fields.
 Alexis received her PhD in physics from Queen's University in Kingston,
 and has worked as a researcher at universities in New Zealand and Canada.
 Alexis currently splits her time between working as an R&D scientist at
 
\emph on
Octane Biotech
\emph default
 and running her consulting business, 
\emph on
Mindshine Scientific
\emph default
 (which tackles projects such as BETSE).
 Alexis first became interested in bio-electrochemical phenomena and their
 implied role in biological pattern formation after becoming aware of Dr
 Levin's research in 2008.
 In 2013, Alexis set out to create an efficient, flexible, and bio-realistic
 model that would help explore bio-electrochemical phenomena in the context
 of spatio-temporal pattern formation, which eventually grew into the BETSE
 project.
 
\end_layout

\begin_layout Standard
BETSE relies heavily on open-source software tools developed for scientific
 computing, for which special mention and thanks goes out to:
\end_layout

\begin_layout Itemize
NumPy 
\begin_inset space \qquad{}
\end_inset


\emph on
the fundamental package for scientific computing in Python, especially essential
 for matrix math
\end_layout

\begin_layout Itemize
SciPy Library
\begin_inset space \qquad{}
\end_inset


\emph on
a suite of additional tools for scientific computing in Python
\end_layout

\begin_layout Itemize
MatplotLib
\begin_inset space \qquad{}
\end_inset


\emph on
a suite of plotting tools for data visualization
\emph default
 
\end_layout

\begin_layout Itemize
IPython
\begin_inset space \qquad{}
\end_inset


\emph on
an advanced interactive console used extensively in BETSE development
\end_layout

\begin_layout Standard
You can contact Alexis at: alexis.pietak@gmail.com and Cecil at leycec@gmail.com.
 
\end_layout

\begin_layout Section
Appendix
\begin_inset CommandInset label
LatexCommand label
name "sec:Appendix"

\end_inset

 
\end_layout

\begin_layout Subsection
Available Colormaps
\begin_inset CommandInset label
LatexCommand label
name "sub:Available-Colormaps"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/colormaps_reference_00.png
	width 75text%

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/colormaps_reference_01.png
	width 75text%

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/colormaps_reference_02.png
	width 75text%

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/colormaps_reference_03.png
	width 75text%

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename FigureFodder/colormaps_reference_04.png
	width 75text%

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\end_body
\end_document
