The xfit class

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 in MATLAB and the xolotl neuron and network simulator

The first step in using xfit is to create a xfit object using:

xf = xfit();

Properties

Every xfit object has the following properties. To access a property, use dot notation, e.g.:

xf.x

You can view all the properties of an xfit object using the built-in properties command:

properties(xf)

best_cost

The best cost holds the lowest value computed by the simulation function during an optimization procedure. This is a read-only property.

data

Default Allowed values Type
[] any any

The data property can hold any user-defined data. You may want to use this if your cost function required additional data to measure the cost. For example, if you want to fit a neuron to a specifiy voltage trace, you would store it here.

engine

This option determines the optimization algorithm used.

Engine Name Engine Keyword
Pattern Search patternsearch
Particle Swarm particleswarm
Genetic Algorithm ga

lb & ub

Default Allowed values Type
[] vectors double

lb and ub are x 1 vectors of numerical lower bound and upper bound values. During optimization, parameters are bounded between their upper and lower bounds.

nonlcon

Nonlinear inequality and equaity constraints, only supported for engines that support them. To understand how to use these constraints, look at MATLAB's documentation here

options

This property is a struct that holds options for the selected optimization engine. It is automatically generated from MATLAB's built-in optimoptions function.

parameter_names

Default Allowed values Type
[] any cell

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

Default Allowed values Type
[] vector double

The seed is an x 1 vector of numerical parameter values for starting an optimization protocol, where is the number of parameters to optimize over.

SimFcn

Default Allowed values Type
[] any function_handle

A function handle to the simulation function used to evaluate the model cost. 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 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 SimFcn using the xolotl object stored in the x property, which has been set up with trial parameters.

timestamp

This property keeps track of the duration of a simulation. This is a read-only property.

x

Default Allowed values Type
[] scalar values xolotl

This property contains a xolotl object. Since xfit uses xolotl to run actual simulations, this is necessary for all projects.

Methods

evaluate

Syntax

c = evaluate(self,params);

Description

Updates parameters in the xolotl object using params (a vector), evaluate the cost function, and return a cost (a double).

It is assumed that you have the following things configured in the xfit object:

  • x (the xolotl object)
  • SimFcn
  • FitParameters

See Also

find

Syntax

xf.find()
xf.find('MaxTime',1e6)
xf.find('NModels',42)

This method keeps finding solutions and saving them, and is designed to run indefinitely till you manually stop it.

See Also

fit

Syntax

best_fit_params = xf.fit;

Description

Assuming xf is a xfit object, runs the optimization algorithm in an effort to minimze the cost function using specified conditions. Returns a vector of the best-fit parameters. Only the last (best-fit) value is returned.

The best-fit value is also used to update the seed.

See Also

save

Syntax

xf.save()

Description

Assuming xf is a xfit object, save results of this optimization run in a database called .xfit where is the hash of parameters that will be saved

See Also

show

Syntax

xf.show()

Description

Assuming xf is a xfit object, and you have run the xfit algorithm many times and run xf.save, and you have been saving results to a .xfit file, then this method runs the user-defined ShowFcn and goes over all the results If ShowFcn is not defined, then it simply plots the result

See Also