Requirements Document

wrackbaaMobile - Wireless

Dec 10, 2013 (3 years and 6 months ago)

50 views








Requirements Document


Project Name:

Markov Chain Modeling


Customer:

Susan Lincke, Ph.D.


Date:

March10, 2008


Revision: Version
2
.5


Author
(s)
:

Richard Zurad


2

Requirements Document

1.

Introduction

1.1 Purpose

of the Requirements Document

The purpos
e of this document is to record all requirements of the Markov Chain
Modeler and what shall be included in the final program
that is
given to the customer. It
will describe all of the
current
functions of the system as well as a
new additions and
features
. This document will not describe the method by which these requirements will
happen.

This docum
ent will be a basis for the current and future extension

of the
application and will be approved by the customer before continuing.


1.2 Scope

of the Project

The scope of this project will include everything mentioned in this document.
Beyond that, features will be added to the project

based on time available.

Since this

project is a continuation from a previous semester, all requirements from the previous
bui
ld will be listed as well as the requirements for all new features to be implemented.


1.3 Definitions, acronyms, and abbreviations



Markov Chain
-

a discrete
-
time stochastic process with the Markov property
.



Markov Property
-

the probability distribution o
f the current state is conditionally
independent of the path of past states
.



KD
-
Tree
-

a space
-
partitioning data structure for organizing points in a k
-
dimensional space
.



Interpolation
-

a method of constructing new data points within the range of a
discre
te set of known data points


1.4

References

Lincke
-
Salecker, Susan. "Integrated Networks Problem." 2004.

Falcon, James; Olson, Mark. "Markov Chain Modeling Requirements Document
-


Version 1.0" 2007.


1.5

Overview of Remainder of Document

This document giv
es a high level overview of the project's requirements, as well as
accompanying low
-
level descriptions and diagrams that pertain to the project.

2.

General Description

2.1 Product Perspective


An application such as the Markov Chain Modeler is useful in any s
cientific field
where Markov Chains are used
to
analyze data. For example, Markov Chains are used in
physics, information theory, data mining, web crawling, biological modeling, and even
music (algorithmic music composition). Due to the very nature of Mark
ov Chains being
mathematical in nature, the expected characteristics of any user of this application can
range from
knowledgeable computer users to proficient computer users from a more
scientific and technical background.



3

2.2 Product Functions


The Mark
ov Chain Modeler is a tool which can be used to calculate the
probabilities of different combinations of sessions being applied to a network. The
program will include a user
-
friendly GUI, allowing the user to create, link, and view
nodes with ease.


The u
ser has the ability to graphically create and edit the graph based on the following
rules:

1.

Each state is able to have
n

numbers inside based on its location in the
n
-
dimensional graph.

2.

States have the ability to be linked to one another.

3.

Each link has on
e or more variables associated with it.

4.

There exists a way to assign values to each variable.

5.

An equation defines how the variables work together.


Once the graph is created, the user can then create the probabilities table. This will
calculate the prob
abilities of combinations of sessions being applied to the network
graph.


During program runtime, the user has the ability to create a new model, load a previously
created model, and save a current model to be opened later. States and transitions can be
added, removed, and modified through a context menu on the drawing surface.
Since the
principal of the Markov Chain Model is rooted in mathematics, it would not be complete
without the option to define equations and variables to be used in its calculations
.
Variables can be defined globally for a model which can then be used to form equations
for any given state transition. At any given time, the user can then generate the statistics
for the current model and view them.

Also, at any given time, the user wil
l be able to
print out the current diagram via the main context menu.

To cut down on possible repetition in creating states, special
connections

can be
added that are defined as interpolation
connections
. Interpolation
connections

can
appear
as a single no
de with an ellipsis for values

or as every state that is interpolated
, however
they act by interpolating information between two states. For example, consider the two
states 0,1 and 0,30. If the user wished to add states 0,2, 0,3, 0,4 … all the way up to 0
,29,
it would be a long and tedious task.
By
linking two states together via

an interpolation
connection

between states 0,1 and 0,30, the user can then define an interpolation
function, such as
0,
+1.
The interpolation
connection

will then generate all of t
he states
between its
connected

state
s
.
Using the example from above, if state 0,1 connected to
state 0,30 with an interpolation connection, then the interpolation function would be
0,
+1
.
This would create the states 0,2 through 0,29

between states 0,1 and

0,30 (note that based
on this function definition structure, the function

0,
-
1

would achieve the same result

if the
connection was started at state 0,30 and ended at state 0,1
).
Transitions
are also
interpolated across the incoming transition and the outg
oing transition of the interpolation
node.
Since the generated transitions behave as normal transitions, the view can be
expanded to show all the generated states, rather than a single state with an ellipses (all
generated states would be designated a
s

so

by being drawn in a different color.



4


Figure 1

Example of an Interpolation Node's Functionality


Since all the generated states are actual states, they can be edited after they are
generated, allowing the user to modify the states' transitions or connec
t other states to it,
etc.
Interpolation nodes may have the ability to operate in higher dimensions, depending
on time constraints.


2.3 General Constraints


In its current state, the Markov Chain Modeling program exists and functi
ons well
enough to be pub
lished, however it is severely lacking in features and very buggy. As it
stands, the logic code is not independent from the GUI code, and many of the additional
features that need to be implemented depend on separating the GUI code from the logic
cod
e. Onc
e the GUI and logic have been properly split into proper subsystems, the other
smaller requirements should follow suit without terrible difficulty.


The separation of code is to take an estimated two weeks. Afterwards, the
following features will be implem
ented, depending on time constraints.
Currently,
transitions do not have an easy method of being viewed by the user without clicking a
series of mouse buttons and looking at a table; this will be fixed by drawing the value of
the transition on the GUI near

the center of each transition

(see Figure 1)
. Interpolation
nodes currently do not exist and will need to be added, however before they can be
completely implemented,
a smaller feature

need
s

to be added first. On the GUI, states
currently have free
-
reign
to be drawn wherever they please, which will make
interpolation no
des very difficult to implement.
To fix this, a snap
-
to
-
grid feature will
need to be added, which constricts the movement of states to a seen or unseen grid.
Once
this small feature

is

in pl
ace, then the interpolation nodes can be added. The additional
feature of being able to print the current model may be implemented depending on the
time constraints, or priority shifted if it is deemed simple enough to implement over
another feature that h
as become impossible to implement due to time constraints.


5

All work must be completed by May 6th, 2008. All subsystems must be either
completed and functional, or completely hidden from the user until such time as they are
made functional by the next group
.

3.

Specific Requirements

3.1 Use Case

The following diagram shows everything the user
is

able to do in the system. Following
the diagram will be a set of descriptions describing in great detail each component of the
us
e case diagram.
Together, the diagram
and descriptions should exactly how and in what
ways the user shall be able to interact with the system
:



6


Figure 2

UML Use Case Diagram for Markov Chain Modeler Program


Use Case
:
CreateNewModel

ID
: 1

Brief description
: User starts a new model

Primary ac
tors
: User


7

Secondary actors
: None

Preconditions
: None

Main Flow
:

1. The use case starts when the User selects “
New


from the File Menu
.

2. If the current model has been modified


2.1 The system prompts User to save changes.


2.2 If user answers

“Yes”


2.2.1 The system opens “Save Dialog”.

3. The system prompts the user for a title and author of the new diagram.

4. The user enters in a title and author name and presses OK.

5. The system prompts the user for attribute names for the new

diagram.

6
. The system c
lear
s

the curr
ent model and create new buffer and a new drawing window

for the user to work with.

Postconditions
:
The drawing window has been cleared and there is no model on the

screen.

Alternative flows
: None




Use case:

Save
C
urrentModel

ID
: 2

Brief description
: The User saves the current model to disk

Primary actors
: User

Secondary actors
: None

Preconditions
: None

Main Flow
:

1. The use case starts when the User selects “Save” from the File menu.

2. The system opens the “Save
Dialog”.

3. The user specifies a pathname and filename for the file.

4. The system saves the diagram to the hard drive and goes back to the drawing window.

Postconditions
: The m
odel is saved to a file on disk with the extension .mkc

Alternative flows
: None








Use Case:
LoadExistingModel

ID
: 3

Brief description
: The User loads a model from disk

Primary actors
: User

Secondary actors
: None

Preconditions
: None

Main Flow
:


8

1. The use case starts when the User selects “Open” from the File Menu.

2. If the cur
rent model has been modified


2.1 The system prompts User to save changes.


2.2 If user answers “Yes”


2.2.1 The system opens “Save Dialog”.

3. The system opens “Load Dialog”.

4. User selects a file to load.

5. The system loads the
model into the buffer and displays the model on the drawing

screen.

Postconditions
: A model is loaded onto the screen

Alternative flows
: None




Use case
: Add
State

ID
:

4

Brief description
:

User adds a state to the model

Primary actors
:

User

Secondary acto
rs
:

None

Preconditions
:

None

Main Flow
:


1. The use case starts when the User selects “Add State”

from the right
-
click context

menu on the drawing screen
.

2
. The system presents dialog asking for contents of
each
state

attribute
.

3
. The User inputs the

contents.

4
. The system adds the
state to the buffer and draws it on

the screen.

Postconditions
:

A state has been added to the model

Alternative flows
:

None




Use case
: RemoveState

ID
: 5

Brief description
: The User removes a state from the screen

Primar
y actors
: User

Secondary actors
: None

Preconditions
: A state currently exists

Main Flow
:

1. The use case starts when the User right
-
clicks on a state and selects “Remove State”

from the drawing window context menu.

2. The system removes the state and al
l connected links from the buffer and erased from

the screen.

Postconditions
: The selected state has been removed

Alternative flows
: None




9


Use case
: Edit
State

ID
:

6

Brief description
:

The user edits the contents of a state

Primary actors
:

User

Secondary

actors
:

None

Preconditions
:

A state currently exists

Main Flow
:

1. The use case starts when the User
right clicks on a state and
selects “Edit State”

from

the drawing window context menu
.

2
. The system presents a dialog asking for contents of the state

attribute values
.

3. The user inputs the content changes, if any
.

4
. The system replaces the old contents of
the state with the new contents in the buffer

and updates the drawing window to reflect the changes.

Postconditions
:

None

Alternative flows
:

No
ne




Use case
: Add
Transition

ID
:

7

Brief description
:

The user adds a directed link between two states

Primary actors
:

User

Secondary actors
:

None

Preconditions
:

Two states currently exist.

Main Flow
:

1. The use case starts when the User
right
-
clicks on
a state and selects “Add Transition



from the display window context menu
.

2
. The User clicks on the state the link will go to.

3
. If link currently exists between the two states with a link in the same direction


3
.1 Do nothing

4
. The system prompt
s user to enter transition
equations
.

5
. The User enters transition
equations
.

6
. The system draws a directional transition link on the s
creen and places the information

in the buffer.

Postconditions
:

None

Alternative flows
:

None



Use case
: EditTransit
ion

ID
:

8

Brief description
:

The user edits a link between 2 states

Primary actors
:

User

Secondary actors
:

None

Preconditions
:

Two states exist with a link between them

Main Flow
:


10

1. The use case starts when the User
right clicks on a state and
selects “E
dit

Transition



from the display window context menu.

2
. The system prompts the User for new transition
equations
.

3
. The User enters the variables.

4. The system updates the transition values in the buffer and updates the display to

reflect the chang
es

Postconditions
:

None

Alternative flows
:

None



Use case
: Remove
Transition

ID
: 9

Brief description
:

The User removes a link from two states

Primary actors
:

User

Secondary actors
:

None

Preconditions
:

A link currently exists between two states

Main Flow
:

1
.
The use ca
se starts when the User right clicks on a state and selects“Remove

Transition


from the display window context menu
.

2. The user clicks on the state that connects to the clicked state via the transition to delete.

3.
The system r
emoves the tra
nsition from the buffer and updates the display to reflect the

changes.

Postconditions:

The link has been deleted.

Alternative flows
:

None



Use case
: DefineVariable

ID
: 10

Brief description
:

The User define a variable that can be used

on the graph

Primar
y actors
:

User

Secondary actors
:

None

Preconditions
:

None

Main Flow
:

1.
The use case starts when the User selects “
Equation Variables” from the Edit menu.

2
. The system
displays a window allowing the user to enter in variable names and values

3. The user e
nters in a name and a value for all the variables he/she wishes to use on the

graph. The user may also edit previously entered values at this time.

Postconditions
:

None.

Alternate Flows
: None

Use case
: ComputeGraph

ID
: 11

Brief description
: The table of p
robabilities is computed based on the model

Primary actors
: User

Secondary actors
: None

Preconditions
: A model with transitions exists and is currently open on the display

window.


11

Main Flow
:

1. The use case starts when the User
right
-
clicks anywhere on t
he display window and

selects “
Generate Statistics” from the display window context menu.

2. The system computes the table of probabilities and saves it to the buffer, which can be

then viewed in the "Model Statistics" window in the "Edit" menu.

Postcond
itions
: The table of probability values has been calculated

Alternative flows
: None




Use case
: OptimizeModel

ID
: 12

Brief description
: The underlying KD
-
Tree structure is rebalanced to improve

calculation and drawing efficiency.

Primary actors
: User

Se
condary actors
: None

Preconditions
: A model with at least one state exists and is currently loaded in the
display window.

Main Flow
:

1. The use case starts when the User right
-
clicks anywhere on the display window and

selects “Optimize” from the display
window context menu.

2. The system refactors and balances the underlying KD
-
Tree data structure. The user
does not see any evidence that this is happening and will not notice.

Postconditions
: The KD
-
Tree has been balanced.

Alternative flows
: None



Use cas
e
: CreateInterpolation

ID
: 13

Brief description
:
An interpolation connection has been added by the user, and states
and transitions have been generated and added to the buffer

Primary actors
: User

Secondary actors
: None

Preconditions
:
A model is open where

two unconnected states exist

Main Flow
:

1.
The use case begins when the user right clicks on a state
or an interpolation node
and

selects "Interpolation Connection" from the display window context menu.

2. The user click
s on the state that is the end of

the interpolation

2.1. If the state selection is invalid



2.1.1. The system displays an error describing why the selection is invalid.



2.1.2. The system returns to the drawing window.



2.1.3. The use case ends.

3. The system displays a window promptin
g the user for a transition function and
one
forward and one reverse transition equation.

4. The system validates the user's data


4.1 If the user's data is invalid


12



4.1.1. The system displays an error describing why the data is invalid.



4.1.2. The syst
em returns to step 3.

5. The system creates the interpolated nodes and adds them to the buffer and updates the

display to reflect the changes. If the display is in debug mode, each interpolated
state is drawn on the canvas. If the display is in release mo
de, the display simply
shows an interpolation node.


Postconditions
:
In
-
Between states have been generated and are now drawn on the board

and saved in the buffer
.

Alternative flows
: None


3.2 Prototype

The following prototypes are designed to give the cus
tomer a good idea of what the final
product will look like, however some of the drawing styles may change before the final
product is complete.


3.2.1 Equation Variable Dialog Window



Figure 4

Equation Variables Dialog Window






This dialog allows the
user to define variables that can be used in transition
functions and interpolation functions. Using the buttons on the right hand side of the
dialog, the user can add, remove or edit variables and their values. The variables defined
here exist globally fo
r the model. To use one of these variables in a transition function,
the user can enter @(<variable_name>) in the function, where <variable_name> is the

13

name of the
variable defined in this window. See section 3.2.2 for more information on
this topic.




3
.2.2

Edit/Add Transitions Dialog Window



Figure 4

The Edit/Add Transitions Dialog Window


This dialog can only show you the outgoing transitions for a state.

Figure 4

above
depicts the
three
outgoing transitions for state (1,1), rather than the six trans
itions that
touch this state (three incoming, three outgoing). Also in the above example, each
transition has been assigned a value that is a simple linear equation where
@(<variableName>) is the name of a variable that has been defined
by the user in the
Equation Variable Window (see section 3.2.1 for more information)
. Note that more
complex equations can be assigned to transitions, such as 3*@(mu)+4*@(Ls).
Be
mindful of operator precedence that happens during equation evaluation, show below in
Table 1:


Operator

Precedence

*

0

/

0

+

1

-

1

Table 1: Operator Precedence


3.2.3 Attribute Names Dialog Window



14


Figure 5

Attribute Names Dialog Window



This dialog appears during the initial creation of the model. The list of attributes
that the model will
use is entered in by the user in this dialog. Note that after the model
has been created, the user is no longer able to add or remove attributes from the
model;

only change the names of the attributes.


3.2.4 Add/Edit State Dialog Window



Figure 6

Add/Ed
it State Dialog Window


15


The user adds and edits states in the model using this dialog window. After
selecting Add State or Edit State from the display window's context menu (right click on
display window or state), the user is presented with this dialog wi
ndow, allowing changes
to
be made for
each attribute. The list of values that can be added contains the same
attribute names that were defined in the Attribute Names Dialog Window at model
creation time (see section 3.2.3 for more information).


3.2.5 Mod
el Statistics Dialog Window


Figure 7

Model Statistics Dialog Window




This form has two tabs that display the generated statistics for the current Markov
Model. This window is not available until the user selects "Generate Statistics" from the
display w
indow
'
s context menu. Once the statistics are generated, this form can be
viewed by going to the Edit menu and clicking Model Statistics.


3.2.6

The Main Form Dialog Window



16


Figure

8

Markov Chain Modeler Main Dialog Window


With the Display Window's Con
text Menu Open


This is the main form for the Markov Chain Modeler project. It simply consists of
the display area wh
ere all of the drawing is done, and
a main menu at the top consisting
of File, Edit, and Help menus.


The File menu contains the following
options:



New, allowing
the user to create a new model;



Open, allowing the user to open a m
odel that was previously saved;



Save, allowing the user to sa
ve the current model to a file;



Save As, allowing the user to save the model to a file diffe
rent from th
e
current file



Exit, which will obviously terminate the program.

The Edit menu contains the following options:



Project Details, allowing the user to see the information about
the project
(title and author)



Attribute Names, which displays the default stat
e attributes and allows the
user to change the attribute names (recall that once the model has be
en
created, this window will not

allow the user

to add or remove attributes)



Equation Variables, which allow the user to define variables

to use in
transition
functions


17



Model Statistics, which show the user the statistics generated by the
current model

(recall that this is not available until the user selects
Generate Statistics from the display window's context menu)
.

The Help menu contains and About button, w
hich displays a simple form showing
the user information about the program and its creators.


There is also a hidden context menu in the display area that can be accessed by
right clicking anywhere in the display area (show above).
This context menu has t
he
following options:



Add State, allowing the use
r to add a state to the diagram



Edit State, allowing the user to edit the val
ues of the state that was right
-
clicked on




Remove State, allowing the user to
delete the state that was right
-
clicked
on (along
with all transitions that go

to and from the deleted state)




Add Transition, allowing the user to add an outgoing transition from the
state
right
-
clicked on to a state chosen by the user (also adds an incoming
transition to the clicked on state fro
m the st
ate chosen by the user)




Edit Transition, allowing the user to edit the values of all the outgoing

transitions of the state right
-
clicked o
n



Remove Transition, allowing the user to remove an outgoing
transition
from the state right
-
clicked on



Interpolation

Connection, allowing the user to create in
terpolated nodes
from the right
-
clicked state to
a state of the user's choosing



Optimize, which will balance the underlying KD
-
Tree data structure at the
user's wi
ll, increasing performance



Generate Statistics, al
lowing the user to generate the statistics for the
current model and view them via the Edit

Model Statistics dialog
window.


3.2.6 Create Interpolation Connection Dialog Window



Figure 9

The Interpolation Connection Dialog Window



18


This is the window th
at that allows the user to define an interpolation connection
between two states. The transition function determines the interval that the state's values
take as they are generated from start to finish.
Note that equations can be used just like in
normal t
ransitions, however interpolation connections get the added variable of S1, the
values of the start state attributes, and S2
, the values of the end state attributes.
The
transitions group box is where the user defines how the transitions will be interpolat
ed
across states. Incoming and outgoing transitions are further defined by their direction, for
example the forward transition is the transition that goes to the first interpolated state
from the start state, and the
reverse transition
is the transition th
at goes from the
first
interpolated state to the start state
. Transitions are optional and if they are left empty, null
(red) transitions will be inserted across the generated states. The settings in Figure 9 can
be used to generate the green states in Fig
ure 10 (see section 3.2.6)



3.2.6
An Example of an In
-
Progress Model



Figure 10

An Example of a Markov Chain being modeled



Figure 10 shows an example of what the Markov Chain Modeler will look like in
use. The image also shows an example of interpolat
ion connections in use. There are four
states defined by the user (the grey circles), two states generated by interpolation
functions shown in debug mode (the green circles), and one interpolation node in release
mode (the ellipses between state 0,1 and 0,
30).
T
ransition
s between the states are

colored

19

either blue or red. Blue transitions have a value which is displayed near the center of the
transition, and red transitions do not have values assigned to them and are therefore null.
In the example, the gree
n nodes were generated by an interpolation connection with the
following values: 1,0 for the interpolation function, 2m for one incoming transition going
to 4m for the corresponding outgoing transition, and m for both incoming and outgoing
transitions in t
he opposite direction (the interpolation connection would have been started
at state 0,1 and ended at state 3,1).


In future releases, it is expected that the start and end nodes could be interpolation
nodes. In this case, new states would not be created,
but new links would be added to
existing interpolated states.



3.3 Design constraints


Since the Markov Chain Modeling program is written in C# with unmanaged C++
and a SQLite database, it will not run on any random desktop computer. Because of the
unmana
ged C++ code that is essential to the calculation engine, the program must be
executed on a Microsoft Windows operating system that has the .NET framework 2.0
installed. If the C++ engine was ported to C#, the program could then theoretically run on
a Linu
x/Unix desktop through the Mono project (a Linux port of the .NET framework),
however a port of the C++ engine to C# will reduce calculation performance. It is the
group
'
s understanding that there are no constraints that deal with the SQLite engine other
t
han SQLite must be installed on any development machines in order to build the project
(this should not affect deployment machines). The hardware of the deployment machine
should not have too much of an effect on the behavior and performance of the program

more
-
so than any other program; if the machine has copious amounts of memory and a
fast processor, it will obviously perform calculations much faster than a machine with
less memory and a slower processor.


No other constraints that pertain to the Markov

Chain Modeling program
that
warrant attention are known at this point.


3.4

Non
-
functional Requirements

Speed and efficiency are keys to the success and usability of this program. Since
the application's primary function is calculating statistics with ver
y large matrices, the
performance of these calculations are important, which is why the calculation functions
are programmed in unmanaged C++. The calculation results and interface do not require
the added efficiency of unmanaged C++ and therefore will be
written in C#. For
compatibility reasons, all the code work is to be done in the Visual Studio 2005
Integrated Development Environment. Upgrading to Visual Studio 2008 is not needed at
this time. To store models on the fly and permanently, all of the infor
mation will be saved
in an embedded SQLite database.

Security of program files is not an issue, as the information generated by the
Markov Chain Modeler program is not deemed to be sensitive information. Files that are
generated and information that is st
ored in memory do not require and thus do not
implement any security precautions other than those needed to ensure program stability.
Any further security measures that the user deems necessary will need to be implemented
by the user, and not by the system
.


20

The Markov Chain Modeler program assumes that the user is familiar with the
subject of Markov Chains and understands the mathematics and concepts behind them.
The Markov Chain Modeler program will not be responsible for informing the user
about
what a Ma
rkov Chain is or go into detail about any of the functions that it calculates, as it
will assume the user already has a thorough understanding of them.

The program does
not require the user to be proficient with computers in general as its user interface i
s
designed to be as user
-
friendly as possible. No complex instructions or commands are
needed to utilize all functionality of the Markov Chain Modeler program. If the user has
an understanding of computers that is well enough to write text documents and br
owse
the internet, then the user should be computer
-
literate enough to navigate through the
Markov Chain Modeler program.