Documentation File for DialysisClearanceGUI

Author: Tucker Burgin
Contact: tuckerburgin@gmail.com
Date: March 18, 2016
Version: 1.0

This text file documents in as complete a manner as possible the operation
and design of the DialysisClearanceGUI MATLAB program and its dependancies.

The purpose of the DialysisClearanceGUI is to make available to researchers
in the University of Rochester's McGrath Lab and collaborators the models
I've constructed for the transport of solutes in tangential flow in a
dialysis-style device. This document will include a description of the
program and a broad overview of its design rationale, and will proceed into
technical descriptions of its main function and the functions on which it
depends. All of these functions should be available in the folder called 
'DialysisClearanceGUI', which can be found on the McGrath Lab website.

Please feel free to contact me with any questions you may have. While my
memory may wane after a long enough time, I'll always do my best to be of
assistance!

TABLE OF CONTENTS
    I.   THE MODEL SYSTEM
    II.  QUICK-START TUTORIAL
    III. THE GUI ELEMENTS IN DETAIL
        A. 'Which model?'
        B. 'Dialyzer Characteristics'
        C. 'Solutes'
        D. 'Hybrid Model Options'
        E. The unmarked textbox
        F. The plot area
        G. The 'Simulate' button
    IV.  THE GUI CODE
    V.   DEPENDANCIES


I. THE MODEL SYSTEM

The models are designed to predict the transport behavior of solutes in
water at 273.15 K as it flows through a narrow channel bounded on one side
by an impermeable wall and on the other by an ultrapermeable membrane. A
more complete description of the system (and the analytical model) can be
found in the publication 'Analytical and Finite Element Models of
Hemodialysis for Miniaturized, Continuous Treatment' by Burgin et al., in
the journal Membranes, 2016.

The GUI returns three pieces of information for each simulation: the
fractional clearance of the solute, which is the fraction of the solute
that was removed from the solution in the course of its passage through the
dialyzer; the steady-state concentration, which is the concentration of the
solute at which the total clearance rate is equal to the rate of solute
production in a model patient being dialyzed continuously by this device
and with the rate of solute generation given for the solute (more on this
can also be found in the aforementioned publication); and a plot of the
concentration profile of the solute or solutes, the format of which depends
on the type of model employed.


II. QUICK-START TUTORIAL

For users interested only in obtaining approximate results without worrying
about the nuances of the simulations, the following tutorial is provided:

1) Select the 'Analytical Model' option in the 'Which model?' box.
2) Enter the dialyzer information of your system in the 'Dialyzer
   Characteristics' fields. The first four fields are required; however,
   the 'Pore Image Name' field can be left blank, in which case the program
   will default to the 'wafer1132ALD2nm_im7_r.mat' file provided.
3) Select the solutes you're interested in with the 'Solutes' checkboxes.
   Any number can be selected together, but if any custom solutes are used,
   the solute Radius fields are mandatory.
4) Press 'Simulate' and, on slower machines, allow the simulation some time
   to run. Your results will appear on the right side of the GUI.


III. THE GUI ELEMENTS IN DETAIL

This section is divided into subsections. Each of the major elements of the
GUI is described, and then more detail is given for each in turn.

The GUI consists of a single window divided into 7 distinct panels:
    'Which model?' - a pair of radiobuttons for selecting the type of model
                    that the program should employ.
    'Dialyzer characteristics' - a set of edit boxes which take information
                                 about the device to be modeled.
    'Solutes' - Six checkboxes to determine which solutes should be modeled
                by the program. Four defaults are given, along with two
                custom options.
    'Hybrid Model Options' - three options for fine-tuning the behavior of
                             the hybrid model, if it is selected.
    The unmarked textbox - a space for the results of simulations to be
                           returned to the user in text form.
    The plot window - a space for graphical results to be plotted.
    The 'Simulate' button - a button to run the selected simulations.

A. 'Which model?'

The function of this section is self-explanatory; however, the distinction
between the models themselves may not be.

Broadly speaking, the analytical model is simply a solution to the
appropriately-constrained expression of the diffsion equation, Fick's
Second Law. Importantly, this model does NOT consider the convective
transport of the solutes being carried along by the fluid directly.
Instead, the convective flow term is assumed to be constant everywhere
within the device, and the velocity is simply used to determine how long
the solution is exposed to the membrane. A more detailed description can be
found in the publication mentioned in Section I of this document.

Conversely, the hybrid model DOES include a direct description of fluid
flow, and simplifies the Convection-Diffusion equation by assuming steady
state. This model solves for the velocity field analytically according to
one of two preset 'velocity profiles' (plug flow or parabolic flow; more on
these shortly) and proceeds to solve the concentration profile numerically
using a built-in MATLAB PDE solver. Thus, the model employes both
analytical and computational methods and is dubbed a 'hybrid'.

The velocity profiles preset for the hybrid model are two of the most
common flow patterns useful in microfluidics. The name of the first,
'plug' flow, refers to the flat, plug-like surface of a velocity profile
that is more-or-less constant across the width of the channel. In this
application, the profile is assumed the be perfectly equal everywhere, and
this is the same assumption made by the analytical model. The name of the
second profile, 'parabolic', is also telling. This model assumes a very
typical parabolic distribution of velocities in the channel, with the
maximum velocity in the center of the channel and with the no-slip boundary
condition dictating zero velocity at the very edges. Both of these profiles
are two-dimensional -- that is, it is assumed that the edges of the channel
perpindicular to the membrane and opposite wall do not interfere with the 
overall profile. This is a reasonable assumption if the channel is 
sufficiently thin.

B. 'Dialyzer Characteristics'

These fields enable the user to control the design of the dialysis device
by editing its geometry, its membrane, and the flow rate.

The 'Membrane Area' field refers to the total ACTIVE membrane area that the
fluid is exposed to. The spatial distribution of this area is not relevant
to this model; assuming a contiguous membrane area, results are identical
regardless of the membrane shape. Non-contiguous membrane area may result
in some small error, especially for the hybrid model.

The 'Channel Height' field refers to the distance between the membrane and
the opposite wall. This is an extremely important parameter in controlling
the results of the simulations.

The 'Flow Rate' field refers to the volumetric flow rate of fluid into the
dialyzer. This parameter directly affects not only the clearance behavior
of the device by changing the time the fluid spends in contact with the
membrane, but is also important in calculating the steady-state
concentration values returned in the output. More on this in section IV.

The 'Pore Image Name' field refers to the filename of the .mat file
produced by the TABS-PoreImageProcessorGUI and corresponding to the
membrane to be simulated by the models. This file is employed by the
function 'finding_dmem' in order to determine the resistance the membrane
poses to the transport of each solute. More on this can be found in section
V, 'DEPENDANCIES'.

The 'Pore Restriction' field refers to the change in pore size the user
wishes to make to the pore image selected for the models. More on this can
be found in section V, but suffice it to say here that this function is
intended to apply a sort of 'digital ALD' that diminishes the size of each
pore by the given size. BE WARNED: This function has not been rigorously
validated by experiments and may not bear any resemblance to reality.

Also important to note is the membrane thickness. Thickness is an extremely
important membrane property, and must be manually set within the
finding_dmem.m code, should you want to change it from its default value of
35nm. Furthermore, it must also be changed in the code for the
DialysisClearanceGUI, where it's called by the variable name 't'.

C. 'Solutes'

This element contains six checkboxes, each corresponding to a different
solute. Four of these six are defaults, chosen for their relevance to
hemodialysis. The remaining two are custom fields, which the user can use
to model the clearance of solutes not originally considered in this work.

Each solute has a corresponding Radius and Generation Rate. The former
refers to the solutes' hydrodynamic radii and is used in predicting their
diffusion coefficients and membrane permeabilities. The latter, to the rate
at which the solute is produced within the body of the patient being
dialyzed. Again, more on this can be found in section IV.

The Radius and Generation Rate of the four default solutes are fixed;
however they are edit fields for the custom solutes. While the radius for a
custom solute is mandatory, the generation rate is not; leaving it blank
will simply return 'NaN' for the steady-state concentration.

D. 'Hybrid Model Options'

This box contains three options: the number of elements employed in the
numerical solver of the hybrid model in each dimension, and the choice of
velocity profile for the same. As these options affect only the behavior of
the hybrid model, they can be safely left blank when the 'Analytical Model'
option is selected. However, they are mandatory for the hybrid model.

The number of elements in each dimension refers to the number of pieces to
cut the computational domain into during descritization. More elements will
be more accurate, but also lead to longer computation times. As always when
working with descritized computational models, a balance should be sought
between accuracy and speed. Note that steeper gradients necessitate higher
numbers of elements to ensure reasonable accuracy, but that after a certain
point, increasing the number of elements will have little or no effect on
the results of the simulation. Reasonable values for both options are
typically on the order of ~50.

The velocity profile selection is described in more detail in part A of
this section.

E . The unmarked textbox

The top-right textbox exists solely to report model results to the user. It
will have one entry for each solute and contains 'fractional clearance' and
'steady-state' concentration. The former of these represents one minus the
average value of the concentration profile. In the case of the hybrid model
the profile is evaluated at the outlet only for this value. The latter is
the concentration at which the solute removed during a single pass is equal
to the concentration increase due to generation within the patient's body
during that same time, based on the solute generation rate, volumetric flow
rate, and fractional clearance. More detail is given in the aforementioned
publication.

F. The plot window

This window exists to provide a visualization of the results of the
simulations. This is given as a 2D plot with a line for each solute for the
analytical model, and a 3D surface plot for the hybrid model.

The 2D plot represents the concentration profile between the wall and the
membrane for each solute after the appropriate residence time in the device
has elapsed -- thus, this is the concentration profile at the outlet. The
profile is normalized to the inlet concentration, whatever that may be;
thus the vertical axis is the fractional concentration.

The 3D plot contains length along the direction of flow on the bottom-left
axis, length from the wall to the membrane on the bottom-right (the wall is
on the far side, while the membrane is closer), and normalized 
concentration on the z-axis. This plot is generated only for the last
simulation to be run to avoid over-crowding. The order in which solute
simulations are run is fixed within the GUI code:

Albumin -> Beta-2-Microglobulin -> Creatinine -> Urea -> Custom1 -> Custom2

G. The 'Simulate' button

This button simply incdicates to the GUI that it is ready to begin the
simulation with the given device characteristics and options. No
computations are performed until this button is used.


IV. THE GUI CODE

The code for the GUI is structured rather simply: all computation is
performed when the 'Simulate' button is pressed, including reading the
contents of edit boxes and other settings. The process flow can be
summarized as follows:

Evaluate settings supplied by user -> For each selected solute, populate
lists containing all solute-specific information -> Run appropriate model
for each solute and populate output strings with results.

The code is not designed to 'catch' most errors, though it does include a
custom error message in the event of a broken model-select button pair. In
the event of omission of required information (such as a custom solute
radius or the number of elements for the hybrid model) MATLAB will return
a fairly cryptic message. These should not be cause for alarm.

More detail in individual processes can be found in the comments for the
code itself.


V. DEPENDANCIES

The GUI depends on three subroutines which are included as functions in the
DialysisClearanceGUI folder. These are:

betaAnalytical: this function is the implementation of the analytical model
employed by the GUI. It evaluates the solution to an analytical function of
time and space and returns the resulting concentration profile. There are
two nuances to this code. First, it needs to evaluate the intersections of
two functions, one of which is dependant on the value of beta passed to it.
This has been written to a fairly high-degree of robustness, but still
fails for exceedingly small values of beta. The GUI code includes a
safeguard against this failure. Second, the function it evaluates is an
infinite sum. While the default number of iterations strikes a good balance
between speed and accuracy, it's concievable that some specific dialyzers
might require more. In general, the analytical model is the least-accurate
(but fastest) method I have employed for making predictions of experimental
behavior -- it is typically good mostly as a first-order approximation.

VelocityProfileDialysis: similar to betaAnalytical, this function contains
the implementation of the hybrid model. It uses the built-in MATLAB pde
solver pdepe.m, which is a numerical method, to solve the steady-state
convection-diffusion equation for a given velocity profile. For more
information on the distinction between the velocity profiles, see the
relevant passage in section III(A). In general, the hybrid model is a
fairly accurate predictor of experimental behavior, especially when using
the parabolic velocity profile, which preferentially clears larger solutes
while retaining smaller ones relative to plug flow behavior.

finding_dmem: this code was originally written by Jess Snyder. It uses a
pore modeling method based on the pore image passed to it in order to
predict an effective diffusion coefficient for a given solute within the
membrane space. It also calculates the free-diffusion coefficient using the
Stokes-Einstein relationship. This is important for evaluating the value of
beta for both models. PLEASE NOTE that this function has not been
rigorously validated by experiments. For more information, see Jess
Snyder's Ph.D. thesis, 'Porous Nanocrystalline Silicon Membranes as Sieves
and Pumps.' When the 'pore restriction' field is set to any value other
than 0, this function also reduces the diameter of each pore in the given
pore image file by that amount before calculating the membrane diffusion
coefficient. Again, this functionality has not been experimentally
validated and should be used only with caution.

wafer1132ALD2nm_im7_r.mat: this file contains a sample pore image outputted
from the PoreImageProcessorGUI. While it is always most accurate to supply
the DialysisClearanceGUI with an electron micrograph image of the membrane
you intend to use, this sample file is included as a default for when the
exact nature of the silicon nanomembrane you want to use is of little
importance. Double-click this file in the MATLAB window's directory tab to
load its contents into your workspace as a structure variable called
'results' before running the DialysisClearanceGUI if you intend to use it.