## Advanced Use

- Run Optimizations in Parallel
- Calculate overlap across a set of samples
- Lock a subset of items in a set

# Running optimizations in parallel within MATLAB

To run multiple optimizations in parallel within MATLAB, you must have the parallel computing toolbox installed (standalone binary users can simply run multiple instances of the binary and set different random seeds each time). With this installed, you can then modify your existing optimization code with the following simple code snippets to your existing optimization files to run the optimization multiple times and record the results:

PREPEND:

matlabpool % starts parallel computing

outcomes = []; % records whether the optimization ended because critteria were met

ind = []; % the index of the current optimization

nSim = 10; % the number of optimizations to run.

parfor 1:nSim %include your script within this loop

Within your script:

Set your sample files to be saved under a different name for each optimization. Assuming the directory './samples' exists, this can be done as follows:

e.g.,

outFile = strcat('./samples/','currentOptimization','s','@',int2str(i),'.out.txt');

s1 = sample(100, 'name','s1','outFile',outFile);

Have the Optimizer's outcome recorded so that you can assess whether the optimization ended successfully (i.e., ended because the statistical critiera were passed).

outcomes(i) = entSOS.optimize();

%if desired, save your files here and print out any post-optimization diagnostic

%information

end % end the optimization here

APPEND:

disp(outcomes);

disp('Percent of cases that succeeded');

percentGood = sum(outcomes(:))/length(outcomes);

disp(percentGood);

matlabpool close

EXTRA OPTIONS:

Additionally, you may wish to log the outcome of each individual optimization. This can be accomplished by adding something like the following to the Prepend section:

diary(strcat('./runLog.',int2str(i),'.txt'));

diary on

And turning off logging in the append section with:

diary off

You
can also add a master diary outside of the parfor over each individual
simulation to record the master process that is controlling each
individual optimization.

# Calculate overlap across a set of samples

To calculate the overlap across a set of samples (e.g., as obtained from running the same optimization many times in parallel), users may wish to download files for additional matlab functions for accomplishing this (which is included in ./helperfunctions in more recent version of the software), which they can modify for their own specific circumstances.

The two matlab functions included in this archive correspond to methods for comparing the overlap between a set of samples that can be run in standard matlab or that require the parallel computation toolbox, respectively. Here, an example with compareOverlap(...) is given:

To use this script, add the path to its location to your matlab path (e.g., add /SOSROOT/helperfunctions to your path or download the standalone zip file, above, and add the extracted contents to your path via addpath('./<LOCATION>').

it will then be possible to call compareOverlap(...) or compareOverlapParallel(...) with the following arguments:

<targDir> - the directory that contains the samples to be compared (and only those samples)

<nSamples> - the number of samples in the directory that you want to compare. This should be less than or equal to the total number of samples in the directory

<sampleSize> - the number of items in each of the samples.

The function will print and return the mean overlap and its standard error, so you can save these results for later printing or use:

[percent, se] = compareOverlap('./samples', 2, 10).

Note that the computational burden of calculating overlap across multiple samples increases rapidly.

# Lock a subset of items in a set

The lockall() command can be used to lock all of the items in a set; however, it is sometimes desirable to only lock a subset of these items (e.g,. to replace a few 'bad' items within an otherwise 'good' set). In this case, include a special 'isLocked' column in your sample data file when it is read into MATLAB. Each entry in this column should contain a '1' for items that should be locked and a '0' otherwise.

Item 'locks' may also be edited manually
by editing the 'isLocked' column within the sample object data directly
once the sample is created. See the source code for the 'sample' object for details.