diff --git a/@xfit/examples/example_func.m b/+xolotl/+examples/burstingCostFcn.m
similarity index 76%
rename from @xfit/examples/example_func.m
rename to +xolotl/+examples/burstingCostFcn.m
index 380af0c6..eb45d0a8 100644
--- a/@xfit/examples/example_func.m
+++ b/+xolotl/+examples/burstingCostFcn.m
@@ -1,4 +1,4 @@
-function C = example_func(x,~,~)
+
 
 % this example simulation function simulates a model
 % and computes the burst period and mean spikes per burst
@@ -7,6 +7,10 @@
 % if the mean spikes per burst is within [7, 10] then that part of the cost is zero
 % otherwise, the cost is the quadratic difference
 
+
+function C = burstingCostFcn(x,~)
+
+% x is a xolotl object
 x.reset;
 x.t_end = 10e3;
 x.approx_channels = 1;
@@ -17,12 +21,16 @@
 x.integrate;
 V = x.integrate;
 
+% measure behaviour 
 metrics = xtools.V2metrics(V,'sampling_rate',10);
 
-C = xfit.binCost([950 1050],metrics.burst_period);
 
+% accumulate errors
+C = xfit.binCost([950 1050],metrics.burst_period);
+C = C + xfit.binCost([.1 .3],metrics.duty_cycle_mean);
 C = C + xfit.binCost([7 10],metrics.n_spikes_per_burst_mean);
 
+% safety -- if something goes wrong, return a large cost
 if isnan(C)
 	C = 1e3;
 end
diff --git a/@xfit/xfit.m b/@xfit/xfit.m
index af4b8241..0b9f1fa1 100644
--- a/@xfit/xfit.m
+++ b/@xfit/xfit.m
@@ -1,13 +1,8 @@
-%                                      _            
-%  _ __  _ __ ___   ___ _ __ _   _ ___| |_ ___  ___ 
-% | '_ \| '__/ _ \ / __| '__| | | / __| __/ _ \/ __|
-% | |_) | | | (_) | (__| |  | |_| \__ \ ||  __/\__ \
-% | .__/|_|  \___/ \___|_|   \__,_|___/\__\___||___/
-% |_|  
-%
-% xfit is a toolbox that attempts
-% to change parameters in a Xolotl object
-% so that it fits some arbitrary set of conditions
+
+% xfit is a toolbox that helps you find neuron or network
+% models satisfying arbitrary constraints. It is a bridge 
+% between the Global Optimization Toolbox in MATLAB
+% and the xolotl neuron and network simulator 
 
 classdef xfit < handle
 
@@ -23,14 +18,14 @@
 	lb
 	ub
 
-	options
+	
 
 	display_type = 'iter'
 	engine 
 
 	% logging
 	timestamp
-	best_cost
+	
 
 	% this can be used to store any user-defined data
 	data
@@ -38,6 +33,12 @@
 
 end % end props
 
+
+properties (SetAccess = private)
+	best_cost
+	options
+end
+
 methods
 	function self = xfit(engine)
 		% check for optimisation toolbox
diff --git a/docs/reference/matlab/xfit.md b/docs/reference/matlab/xfit-head.md
similarity index 72%
rename from docs/reference/matlab/xfit.md
rename to docs/reference/matlab/xfit-head.md
index 9d266ec3..da6341fb 100644
--- a/docs/reference/matlab/xfit.md
+++ b/docs/reference/matlab/xfit-head.md
@@ -1,7 +1,9 @@
 # The xfit class
 
-This document describes the "xfit" class.
-This is a MATLAB class for parameter optimization of xolotl models.
+
+
+This document describes the `xfit` class. `xfit` is a toolbox that helps you find neuron or network models satisfying arbitrary constraints. It is a bridge 
+between the [Global Optimization Toolbox](https://www.mathworks.com/products/global-optimization.html) in MATLAB and the [xolotl](https://go.brandeis.edu/xolotl) neuron and network simulator 
 
 The first step in using `xfit` is to create a `xfit` object using:
 
@@ -11,16 +13,6 @@ xf = xfit;
 xf = xfit('particleswarm');
 ```
 
-## Requirements
-
-xfit is an add-on to xolotl.
-In addition to the core modules,
-xfit requires
-
-* the Parallel Computing Toolbox,
-* the Optimization Toolbox,
-* and the Global Optimization Toolbox.
-
 ## Properties
 
 Every xfit object has the following properties.
@@ -38,8 +30,9 @@ properties(xf)
 ```
 
 ### `x`
-This property contains a handle to the xolotl object.
-Setting this property is essential to using `xfit`.
+
+This property contains a xolotl object. Since xfit uses
+xolotl to run actual simulations, this is necessary for all projects. 
 
 ### `sim_func`
 A function handle to the simulation function used to evaluate the model cost.
@@ -47,22 +40,31 @@ The simulation function can be any MATLAB function,
 provided that the following are true:
 
 * The first output must be the cost, which is a positive, real-valued scalar.
-* The arguments must be `(x, ~, ~)`, where `x` is the xolotl object.
+* The function accepts two arguments, the first of which is a xolotl object.
+
+The function thus has the (minimal) signature:
+
+```
+function [cost, ...] = functionName(xolotl_object, data)
+```
 
 When xfit performs a parameter optimization routine,
 it calls the `sim_func` using the xolotl object stored in the `x` property, which has been set up with trial parameters.
 
 ### `parameter_names`
+
 This cell array of character vectors contains the names of xolotl parameters to optimize over.
 The `find` method of xolotl is the best way to populate this list.
 `seed`, `lb`, and `ub` share one-to-one correspondence with `parameter_names`, so all should be the same dimensions.
 
 ### `seed`
+
 The seed is an $n$ x 1 vector of numerical parameter values
 for starting an optimization protocol,
 where $n$ is the number of parameters to optimize over.
 
 ### `lb` & `ub`
+
 `lb` and `ub` are $n$ x 1 vector of numerical lower bound and upper bound values.
 During optimization, parameters are bounded between their upper and lower bounds.
 
@@ -71,22 +73,26 @@ This property is a struct that holds options for the selected optimization engin
 It is automatically generated from MATLAB's built-in [optimoptions](https://www.mathworks.com/help/optim/ug/optimization-options-reference.html) function.
 
 ### `display_type`
-This option determines the display type. It defaults to 'iter'.
+
+This option determines the display type. It defaults to `iter`.
 
 ### `engine`
+
 This option determines the optimization algorithm used.
 
 | Engine Name | Engine Keyword |
 | ----------- | -------------- |
-| Pattern Search | `'patternsearch'` |
-| Particle Swarm | `'particleswarm'` |
-| Genetic Algorithm | `'ga'` |
+| Pattern Search | `patternsearch` |
+| Particle Swarm | `particleswarm` |
+| Genetic Algorithm | `ga` |
 
 ### `timestamp`
 This property keeps track of the duration of a simulation.
 
 ### `best_cost`
+
 The best cost holds the lowest value computed by the simulation function during an optimization procedure.
 
 ### `data`
+
 The `data` property can hold any user-defined data.
diff --git a/@xfit/examples/run_me.m b/examples/demo_xfit.m
similarity index 87%
rename from @xfit/examples/run_me.m
rename to examples/demo_xfit.m
index 72a2cb3c..fb6164cc 100644
--- a/@xfit/examples/run_me.m
+++ b/examples/demo_xfit.m
@@ -4,13 +4,14 @@
 
 % first, we create our xolotl object
 x = xolotl.examples.BurstingNeuron('prefix','prinz');
+x.set('*gbar',veclib.shuffle((x.get('*gbar'))))
 
 % we instantiate the xfit object
 % and specify the particle swarm engine
 p = xfit('particleswarm');
 
 % we assign a cost function
-p.sim_func = @example_func;
+p.sim_func = @xolotl.examples.burstingCostFcn;
 
 % we assign the xolotl object
 p.x = x;
@@ -26,7 +27,7 @@
 figure('outerposition',[300 300 1200 600],'PaperUnits','points','PaperSize',[1200 600]); hold on
 
 subplot(2,1,1); hold on
-
+set(gca,'XLim',[0 10],'YLim',[-80 50])
 x.t_end = 10e3;
 V = x.integrate;
 time = (1:length(V))*1e-3*x.dt;
@@ -43,11 +44,11 @@
 
 % visualize the results of the optimization
 subplot(2,1,2); hold on
-
+set(gca,'XLim',[0 10],'YLim',[-80 50])
 x.t_end = 10e3;
 V = x.integrate;
 time = (1:length(V))*1e-3*x.dt;
 plot(time,V,'r')
 title('After optimization')
 
-figlib.pretty('LineWidth', 1, 'PlotLineWidth', 1, 'PlotBuffer', 0.2)
+figlib.pretty('LineWidth', 1, 'PlotLineWidth', 1, 'PlotBuffer', 0)
diff --git a/mkdocs.yml b/mkdocs.yml
index a647c252..d1db810f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -48,8 +48,8 @@ pages:
       - xtest: reference/matlab/xtest.md
       - xolotl: reference/matlab/xolotl.md
       - cpplab: reference/matlab/cpplab.md
-      - xfit: ../xfit/docs/xfit.md
-      - xgrid: ../xgrid/docs/xgrid.md
+      - xfit: reference/matlab/xfit.md
+      - xgrid: reference/matlab/xgrid.md
   - How xolotl works:
     - How cpplab binds code: explanation/cpplab.md
     - How equations are integrated: explanation/integration.md