Updated the Read-Me and Release Notes for version 2017b.

README.md

@@ -1,8 +1,8 @@
 # Brain Dynamics Toolbox
 
-##Version 2017a 
+##Version 2017b 
 
-The Brain Dynamics Toolbox provides a convenient graphical user interface for exploring dynamical systems in MATLAB.  Users implement their own dynamical equations (as matlab scripts) and use the toolbox graphical interface to view phase portraits and other plots in real-time. The same models can also be run as MATLAB scripts without the graphics interface. The toolbox includes solvers for Ordinary Differential Equations (ODE), Delay Differential Equations (DDE) and Stochastic Differential Equations (SDE). The plotting tools are modular so that users can create custom plots according to their needs. Custom solver routines can also be used. The user interface is designed for dynamical systems with large numbers of variables and parameters, as is often the case in dynamical models of the brain. Hence the name, *Brain Dynamics Toolbox*.
+The [Brain Dynamics Toolbox](http://bdtoolbox.blogspot.com) provides a convenient graphical user interface for exploring dynamical systems in MATLAB.  Users implement their own dynamical equations (as matlab scripts) and use the toolbox graphical interface to view phase portraits and other plots in real-time. The same models can also be run as MATLAB scripts without the graphics interface. The toolbox includes solvers for Ordinary Differential Equations (ODE), Delay Differential Equations (DDE) and Stochastic Differential Equations (SDE). The plotting tools are modular so that users can create custom plots according to their needs. Custom solver routines can also be used. The user interface is designed for dynamical systems with large numbers of variables and parameters, as is often the case in dynamical models of the brain. Hence the name, *Brain Dynamics Toolbox*.
 
 ## Download
 Dowload the latest release from the [bdtoolkit](https://github.com/breakspear/bdtoolkit/releases) repository on GitHub
@@ -11,7 +11,7 @@ Dowload the latest release from the [bdtoolkit](https://github.com/breakspear/bd
 The toolbox requires MATLAB 2014b or newer. Unzip the toolbox files into a directory of your choosing. The main toolbox scripts are located in the *bdtoolkit* directory which must be in your matlab PATH variable. The *bdtoolkit/models* directory contains example scripts that are also advisable to have in your PATH.
 
 ```matlab
-    $ unzip bdtoolkit-2017a.zip
+    $ unzip bdtoolkit-2017b.zip
     $ matlab
     >> addpath bdtoolkit
     >> addpath bdtoolkit/models
@@ -55,11 +55,11 @@ A typical sys struct has the following structure:
     sys.odefun = @odefun;
     
     % ODE parameter definitions
-    sys.pardef = [ struct('name','a', 'value',-1);
-                   struct('name','b', 'value',0.01) ];
+    sys.pardef = [ struct('name','a', 'value',-1);			% a = -1
+                   struct('name','b', 'value',0.01) ];		% b = 0.01
                    
     % ODE state variable definitions
-    sys.vardef = struct('name','y', 'value',0.9);
+    sys.vardef = struct('name','y', 'value',0.9);			% y = 0.9
     
     % Time span of the solution
     sys.tspan = [0 5];
@@ -86,9 +86,9 @@ The *sys.odefun* field is a function handle to a user-defined function of the fo
     end
 ```
 
-## Plotting Panels
+## Display Panels
 
-The plotting tools (panels) are modular by design so that custom panels may be written by the user. The standard panels are located in the *bdtoolkit/panels* directory. These include time portraits, phase portraits, space-time plots, correlation plots, latex equations and solver statistics. The user may load any panel into the graphic toolbox at run-time. For convenience, the toolbox pre-loads panels that are listed in the model's *sys.panels* options. A typical example is the *bdLatexPanel* which displays mathematical equations using latex. The following example is from *LinearODE.m* which implements a coupled pair of linear Ordinary Differential Equations.
+The plotting tools (display panels) are modular by design so that custom panels may be written by the user. The standard panels are located in the *bdtoolkit/panels* directory. The list of standard panels continues to grow. It currently includes time portraits, phase portraits, space-time plots, linear correlation, Hilbert transforms, latex equations and solver statistics. The user may load any of these panels into the toolbox at run-time. The toolbox also pre-loads those panels that are listed in the model's *sys.panels* options. A typical example is the *bdLatexPanel* which displays mathematical equations using latex. The following example is from *LinearODE.m* which implements a coupled pair of linear Ordinary Differential Equations.
 
 ```matlab
     sys.panels.bdLatexPanel.title = 'Equations'; 
@@ -111,22 +111,43 @@ The `bdLoadMatrix` function is useful for loading matrix data from a file.
 
 The `bdEditScalars`, `bdEditVector` and `bdEditMatrix` functions are useful for interactively editing scalars, vectors and matrices, respectively.
 
+The `Trap Panel` is useful for detecting erroneous drawing commands by user-defined GUI panels. 
+
 ## Going Further
-The best way to proceed is to browse the example code in the *models* directory. The  *LinearODE* model illustrates a simple Ordinary Differential Equation. The *WilleBaker* model illustrates a simple Delay Differential Equation. The *MultiplicativeNoise* model illustrates a simple Stochastic Differential Equation.
+A user manual is currently being written. Until that is published, the best way to proceed is to browse the example code in the *models* directory.
+
+Ordinary Differential Equations:
+
+* *BTF2003ODE* - Breakspear, Terry & Friston (2003) Neural mass model.
+* *FitzhughNagumo* - Generalized FitzHugh-Nagumo neural oscillator.
+* *HindmarshRose* - Network of Hindmarsh-Rose neurons.
+* *HopfieldNet* - Hopfield Network.
+* *KuramotoNet* - Network of Kuramoto phase oscillators.
+* *LinearODE* - A simple Ordinary Differential Equation.
+* *SwiftHohenberg1D* -  Discretised Swift-Hohenberg PDE in one spatial dimension.
+* *VanDerPolOscillators* - Network of Van Der Pol oscillators.
+* *WaveEquation1D* - Discretized wave equation (PDE) in one spatial dimension.
+
+Delay Differential Equations:
+
+* *BTF2003DDE* - Breakspear, Terry & Friston (2003) Neural mass model with time delays.
+* *WilleBaker* - A simple Delay Differential Equation.
+
+Stochastic Differential Equations:
+
+* *BrownianMotion* - Geometric Brownian motion.
+* *BTF2003SDE* - Breakspear, Terry & Friston (2003) Neural mass model with multiplicative noise.
+* *FRRB2012* - Freyer, Roberts, Ritter & Breakspear (2012) Canoncial subcritical Hopf model with multiplicative noise.
+* *FRRB2012b* - Freyer, Roberts, Ritter & Breakspear (2012) Network variant of FRRB2012.
+* *MultiplicativeNoise* - A simple example of multiplicative noise.
+* *Ornstein Uhlenbeck* - Multiple independent Ornstein-Uhlenbeck processes.
+* *RFB2017* - Roberts, Friston & Breakspear (2017) Isolated neural mass with multiplicative noise.
 
 ## BSD License
-This software is freely available under the 2-clause BSD license.  
-
-> Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-> 
->1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
->
->2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
->
->THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+This software is freely available under the [2-clause BSD license](https://opensource.org/licenses/BSD-2-Clause).  
 
 ## Contributors
-* Michael Breakspear, Joint Project Leader 
-* Stewart Heitmann, Joint Project Leader & Lead Developer
+* Michael Breakspear, Project Leader
+* Stewart Heitmann, Project Leader, Lead Developer
 * Matthew Aburn
 

ReleaseNotes.md

@@ -1,39 +1,52 @@
 # Release Notes
 # Brain Dynamics Toolbox
 
-## Version 2017a
-Released 21 March 2017.
+## Version 2017b
+Released 21 June 2017. 
+
+Major new features include:
+(i) Equation parameters and variables can now be directly manipulated from the workspace via the new bdGUI class properties (par, var0, var, lag, t).
+(ii) The System-Save menu now includes solution variables and display panel outputs.
+(iii) Three new display panels were added (bdHilbert, bdSurrogate, bdTrapPanel).
+(iv) Six new models were added (BTF2003ODE, BTF2003DDE, BTF2003SDE, FRRB2012, FRRB2012b, RFB2017).
+(v) Scrollbars were added to the Equations panel. (vi) All panels were refined to make their outputs more accessible to the workspace.
 
 Requires Matlab 2014b or newer.
 
-Major new features:
-(1) Dynamic loading of GUI plot panels.
-(2) Enhanced GUI class properties allow the solver output and panel objects to be accessed directly. 
-(3) New *sys* struct has a more flexible syntax for defining system parameters and variables.
-(4) Improved validation of *sys* structs.
-(5) Time and Phase portraits now support graphic hold.
-(6) All example models have been revised.
+## Version 2017a
+Released 21 March 2017.
+
+Major new features include:
+(i) Dynamic loading of GUI plot panels.
+(ii) Enhanced GUI class properties allow the solver output and panel objects to be accessed directly. 
+(iii) New *sys* struct fromat with more flexible syntax for defining system parameters and variables.
+(iv) Improved validation of *sys* structs.
+(v) Time and Phase portraits now support graphic hold.
+(vi) All example models have been revised.
 
 **This version is not backwards compatible with version 2016a.** In particular: 
-(1) *sys.pardef, sys.vardef, sys.auxdef, sys.lagdef* were changed from cell arrays to struct arrays; 
-(2) *sys.gui* was renamed *sys.panels*;
-(3) SDE function handles were renamed *sys.sdeF* and *sys.sdeG*;
-(4) *bdCorrelationPanel* was renamed *bdCorrPanel*;
-(5) *bdSpaceTimePortrait* was renamed *bdSpaceTime*;
-(6) *odeEuler* was renamed *odeEul*;
-(7) *sdeIto* was renamed *sdeEM*;
-(8) *sdeStratonovich* was renamed *sdeSH*;
-(9) *bdVerify* was renamed *bdSysCheck*;
-(10) *bdUtils* was renamed *bd*;
-(11) The *gui.control* property was replaced by *gui.sys, gui.sol* and *gui.sox*.
-(12) The *sys* fields *tspan*, *odesolver*, *odeoption*, *ddesolver* and *ddeoption* are no longer mandatory.
-
-**Important message to users migrating from 2016a to 2017a.** Scripts written for 2016a will need to be modified to accommodate the changes above. We recommend using *bdSysCheck* when migrating old code. It will quickly detect obsolete and invalid fields in existing *sys* structures. 
+(i) *sys.pardef, sys.vardef, sys.auxdef, sys.lagdef* were changed from cell arrays to struct arrays; 
+(ii) *sys.gui* was renamed *sys.panels*;
+(iii) SDE function handles were renamed *sys.sdeF* and *sys.sdeG*;
+(iv) *bdCorrelationPanel* was renamed *bdCorrPanel*;
+(v) *bdSpaceTimePortrait* was renamed *bdSpaceTime*;
+(vi) *odeEuler* was renamed *odeEul*;
+(vii) *sdeIto* was renamed *sdeEM*;
+(viii) *sdeStratonovich* was renamed *sdeSH*;
+(ix) *bdVerify* was renamed *bdSysCheck*;
+(x) *bdUtils* was renamed *bd*;
+(xi) The *gui.control* property was replaced by *gui.sys, gui.sol* and *gui.sox*;
+(xii) The *sys* fields *tspan*, *odesolver*, *odeoption*, *ddesolver* and *ddeoption* are no longer mandatory.
+
+**Important message to users migrating from 2016a to 2017a.** Scripts written for 2016a will need to be modified to accommodate the changes above. We recommend using *bdSysCheck* when migrating old code. It detects obsolete and invalid *sys* fields. 
+
+Requires Matlab 2014b or newer.
+
 
 ## Version 2016a
 Released 24 Dec 2016.
 
-Requires Matlab 2014b or newer.
+The first public release of the Brain Dynamics Toolbox.
 
-This version is the first public release of the Brain Dynamics Toolbox.
+Requires Matlab 2014b or newer.