From 20f1a256fc71d402671d1779232ca2e6ecb75944 Mon Sep 17 00:00:00 2001 From: "gitlab@srinivas.gs" Date: Wed, 17 Jul 2019 15:22:05 -0400 Subject: [PATCH] rearranged files, added a demo for xfit --- .../+examples/burstingCostFcn.m | 12 ++++- @xfit/xfit.m | 25 ++++++----- .../matlab/{xfit.md => xfit-head.md} | 44 +++++++++++-------- .../examples/run_me.m => examples/demo_xfit.m | 9 ++-- mkdocs.yml | 4 +- 5 files changed, 55 insertions(+), 39 deletions(-) rename @xfit/examples/example_func.m => +xolotl/+examples/burstingCostFcn.m (76%) rename docs/reference/matlab/{xfit.md => xfit-head.md} (72%) rename @xfit/examples/run_me.m => examples/demo_xfit.m (87%) 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