Optimization Functions | XFdtd

A set of utilities which aid user defined optimization.

Optimization in XF is accomplished by writing a simple script using the utility functions provided in Optimization Functions. These functions allow a design to be optimized for gain, S-parameters, efficiency, or other results. The available classes, functions, and variables are defined below.

Optimization is performed in XF by following these steps:

  1. Create a parameterized XF project using parameters in the Parameter List.
  2. Download Optimization Functions and add it to the project by right-clicking on Scripts in the Project Tree and choosing Import Scripts.
  3. Create a separate macro by right-clicking on Scripts in the Project Tree and choose New Macro Script.
  4. Write simple macro code to define the desired optimization with allowable parameter values and goals. The macro will utilize the classes and functions available in Optimization Functions.
  5. Execute the macro to run FDTD simulations and determine an optimal result.
The following code is an example macro that will find the optimal values of the stubLength and microstripLength parameters. The optimization goal is set to maximize realized gain from 746 MHz to 756 MHz.
// define parameters with allowable values
var p1 = new OptimizationParameter( "stubLength", "0.75 mm", "3 mm" );
var p2 = new OptimizationParameter( "microstripLength", "8 mm", "18 mm" );

// define a goal based on Realized Gain
var gainTemplate = getFarzoneResultTemplate( "Far Zone - Single", ResultQuery.RealizedGain, true );
var gainGoal = new GenericResultGoal( gainTemplate, ">", "8 dBi", "0 dBi", "20 dBi", "746 MHz", "756 MHz", "dBi" );

// setup settings for the optimization
var params = new ParticleSwarmParameters;
params.setObjective( params.Maximize );
params.setNumberOfParticles( 10 );
params.setApproximateMaxIterations( 25 );

// create the optimization
var pso = new ParticleSwarmOptimization( params );

pso.addOptimizationParameter( p1 );
pso.addOptimizationParameter( p2 );
pso.addOptimizationGoal( gainGoal );

pso.simulationNamePrefix = "optimize Gain: ";
pso.queueType = "ExternalQueue";
pso.simulationSavingMode = "KeepMilestones";

// run the optimization
var optimalValues = pso.optimize( true );

Particle Swarm Optimization

XF implements a Particle Swarm Optimization (PSO) in the scripting API. The ParticleSwarmOptimization class provided in Optimization Functions stores parameters, modifies the XF project, evaluates goals, and runs FDTD simulations.

class ParticleSwarmOptimization( SwarmParameters swarmParameters )

The high level class that manages the optimization.

swarmParameters Object containing optimization settings, such as number of particles. See the SwarmParameters class in XF's scripting API documentation.

The ParticleSwarmOptimization class has three functions that must be called at least once each to properly configure an optimization.

void addOptimizationParameter( OptimizationParameter parameter )

Adds a parameter to the optimization routine. This function should be called for each parameter that is being optimized.

parameter Container for the name of the XF parameter and the allowable range of values. See the OptimizationParameter documentation below.


void addOptimizationGoal( OptimizationGoal goal )

Adds a goal to the optimization routine. This function should be called for each goal that is being defined.

goal Container for the result type and dimension range to evaluate. See the GenericResultGoal documentation below.


Array optimize( Boolean applyOptimizedValues )

The top level function that runs the optimization.

applyOptimizedValues If true, apply the optimized values to the project when the optimization completes.

Returns a list of parameter values cooresponding to the best solution found.

Additional variables and enumerations are available. Default values are set for each so the user is not required to modify them in order to run an optimization.

String simulationNamePrefix

A user specified prefix to put on each simulation name that is created during the optimization.


Enumeration queueType

Determines if the FDTD simulations will run on a local or external queue. Acceptable values are

"LocalQueue" Run simulations on the local queue.

"ExternalQueue" Run simulations on an external queue with EQI.


Enumeration simulationSavingMode

Indicates which simulations will be saved during the optimization. Acceptable values are

"KeepAll" Keep all simulations that are created (requires most hard disk space)

"KeepMilestones" Keep the simulation that is the best for each iteration of the optimization

"KeepOnlyOptimal" Keep only the final optimal solution and delete all others (requires least hard disk space)

Parameters

The optimization modifies parameters in XF's Parameters List. The parameter name and allowable values are provided for each parameter to be used in the optimization using the OptimizationParameter class.

class OptimizationParameter( String parameterName, String min, String max, String step )

An optimization parameter that by default modifies the XF project by directly manipulating a project parameter.

parameterName The name of the parameter in XF's Parameters List.

min Minimum allowable value the parameter may take. This value may be floating point number, string containing units, or an equation.

max Maximum allowable value the parameter may take. This value may be floating point number, string containing units, or an equation.

step {optional} Determines the allowable incremental values between the minimum and maximum. If this parameter is not provided, the continuous range between the minimum and maximum will be searched. This value may be floating point number, string containing units, or an equation.

Goals

Goals are defined by specifying the result type that should be optimized and specifying the output range of interest within that result. The result type is defined as a ResultQuery and it can be created from scratch for any result or created using one of the five convenience functions provided for common cases.

class GenericResultGoal( ResultQuery resultTemplate, String operator, String thresholdValue, String minValueRange, String maxValueRange, String minDimensionBounds, String maxDimensionBounds, String goalEvaluationUnitAbbreviation )

An optimization goal that loads a simulation result and determines a fitness level.

resultTemplate A result query object that loads the desired result. The user can define their own or use the convience functions provided below.

operator Defines the comparison operator used to compare results to the thresholdValue. Valid strings are "<", "<=", ">", ">=".

thresholdValue The target value that the result is attempting to achieve. This parameter will be evaluated so it is acceptable to provide a string with an equation or units.

minValueRange and maxValueRange Bound the allowable value of a result and its contribution to the fitness of the result. This sets the values where the fitness will evaluate to 0 or 1 depending on the comparison operator specified. This prevents a goal from over powering other goals by driving a single value well above or below the threshold. For example, the desired range may be -10 dB to -20 dB for a design. Although it may be possible to drive this value to -100 dB at the expense of other goals, there is diminishing benefit to reach that level. If a minValueRange of -20 dB were specified anything less than -20 dB would no longer provide benefit to the fitness of the goal.

minDimensionBounds and maxDimensionBounds Single value or array of values that define the subset of the result dimensions over which the goal will be evaluated.

goalEvaluationUnitAbbreviation Allows the user to specify what unit they would like the goal to be evaluated in, for instance "dBa". If this string is empty then backend unit will be used.

Convenience functions are provided which set up result query templates.

ResultQuery getCircuitComponentResultTemplate( String componentName, ResultQuery.ResultType resultType, Boolean useSteadyStateData )

Setup a query for loading a circuit component result.

componentName Name of the Circuit Component in the project.

resultType Indicates which circuit component result (voltage, impedance, etc) to load. See XF's scripting API for the ResultQuery.ResultType enumeration.

useSteadyStateData If true, use steady state discrete frequency data when evaluating this result.


ResultQuery getFarzoneResultTemplate( String sensorName, ResultQuery.ResultType resultType, Boolean useSteadyStateData )

Setup a query for loading a far zone result.

sensorName Name of the Far Zone Sensor in the project.

resultType Indicates which far zone result (gain, directivity, etc.) to load. See XF's scripting API for the ResultQuery.ResultType enumeration.

useSteadyStateData If true, use steady state discrete frequency data when evaluating this result.


ResultQuery getSystemResultTemplate( ResultQuery.ResultType resultType )

Setup a query for loading a system result.

resultType Indicates which System Sensor result (radiation efficiency, net input power, etc.) to load. See XF's scripting API for the ResultQuery.ResultType enumeration.


ResultQuery getPointSensorResultTemplate( String sensorName, ResultQuery.ResultType resultType, ResultQuery.ResultComponent resultComponent, Boolean useScatteredField, Boolean transformToFrequency )

Setup a query for loading a point sensor result.

sensorName Name of the Point Sensor in the project.

resultType Indicates which point sensor result (e-field, h-field, etc.) to load. See XF's scripting API for the ResultQuery.ResultType enumeration.

resultComponent Indicates which component (x, y, etc.) to load. See XF's scripting API for the ResultQuery.ResultComponent enumeration.

useScatteredField If true, load the scattered field result.

transformToFrequency If true, return the frequency-domain equivalent using an FFT.


ResultQuery getSolidSensorResultTemplate( String sensorName, ResultQuery.ResultType resultType, ResultQuery.ResultComponent resultComponent, Boolean useSteadyStateData, Boolean useScatteredField )

Setup a query for loading a volumetric sensor result.

sensorName Name of the Solid Box or Solid Part Sensor in the project.

resultType Indicates which volume sensor result (e-field, h-field, etc.) to load. See XF's scripting API for the ResultQuery.ResultType enumeration.

resultComponent Indicates which component (x, y, etc.) to load. See XF's scripting API for the ResultQuery.ResultComponent enumeration.

useSteadyStateData If true, use steady state discrete frequency data when evaluating this result.

useScatteredField If true, load the scattered field result.