 |
API
4.5.1
For C++ developers
|
|
API
4.5.1
For C++ developers
|
A class for generating Latin hypercube designs. More...
Public Member Functions | |
| LatinHypercubeDesign () | |
| LatinHypercubeDesign (const LatinHypercubeDesign &) | |
| LatinHypercubeDesign (LatinHypercubeDesign &&) | |
| LatinHypercubeDesign & | operator= (const LatinHypercubeDesign &) |
| LatinHypercubeDesign & | operator= (LatinHypercubeDesign &&) |
| void | setNumSamples (int numSamples) |
| The number of samples in the Latin hypercube design (i.e., the number of rows in the design matrix). More... | |
| int | getNumSamples () const |
| The number of samples in the Latin hypercube design (i.e., the number of rows in the design matrix). More... | |
| void | setNumVariables (int numVariables) |
| The number of variables in the Latin hypercube design (i.e., the number of columns in the design matrix). More... | |
| int | getNumVariables () const |
| The number of variables in the Latin hypercube design (i.e., the number of columns in the design matrix). More... | |
| void | setDistanceCriterion (std::string distanceCriterion) |
| The criterion used to evaluate the distance between samples in the Latin hypercube design ("maximin" or "phi_p"). More... | |
| const std::string & | getDistanceCriterion () const |
| The criterion used to evaluate the distance between samples in the Latin hypercube design ("maximin" or "phi_p"). More... | |
| void | setPhiPDistanceExponent (int exponent) |
| The exponent used to evaluate the "phi_p" distance criterion. More... | |
| int | getPhiPDistanceExponent () const |
| The exponent used to evaluate the "phi_p" distance criterion. More... | |
| SimTK::Matrix | generateRandomDesign (int iterations=100) const |
| Generate a Latin hypercube design based on the best design score from multiple random designs. More... | |
| SimTK::Matrix | generateTranslationalPropagationDesign (int numSeedPoints=-1) const |
| Generate a Latin hypercube design based on the translational propagation algorithm from Viana et al. More... | |
| SimTK::Matrix | generateStochasticEvolutionaryDesign (int iterations=10, const SimTK::Matrix &initialDesign={}) const |
| Generate a Latin hypercube design based on the enhanced stochastic evolutionary algorithm from Jin et al. More... | |
| double | evaluateDesign (const SimTK::Matrix &design) const |
| Evaluate the distance between samples in the Latin hypercube design according to the distance criterion specified by the user. More... | |
A class for generating Latin hypercube designs.
A Latin hypercube is an m-by-n matrix, where 'm' is the number of design samples and 'n' is the number of variables in the design. Each sample point (i.e., each row in the design) is the only sample point in its row and column in the hypercube defined by the number of variables.
Latin hypercube designs are useful for sampling large, multivariate parameter spaces. Optimal Latin hypercube designs are those that maximize the minimum distance between samples in the design. This class provides methods for generating random Latin hypercube designs, as well as methods for generating Latin hypercube designs using the translational propagation algorithm from Viana et al. (2009) and the enhanced stochastic evolutionary algorithm from Jin et al. (2005).
To create a Latin hypercube design, you must first specify the number of variables and samples in the design, and, optionally, the distance criterion used to evaluate each design. The distance criterion can be either "maximin" or "phi_p", where "maximin" is the default. The "phi_p" distance criterion is an approximation of the "maximin" criterion that can be used to generate designs that minimize the sum of inverse distances raised to a large exponent (see [2] for more details). The exponent used for the "phi_p" distance criterion can be set using the setPhiPDistanceExponent() method.
For example, a random Latin hypercube design with 10 samples and 3 variables can be created as follows:
A design using the translational propagation algorithm can be created as follows:
A design using the enhanced stochastic evolutionary algorithm can be created as follows:
Finally, each design can be evaluated using the evaluateDesign() method:
Lower design scores are better. Since the original "maximin" is a maximization criterion, here we negate it so it strictly takes on negative values. The "phi_p" criterion returns a positive value since it is a minimization criterion. While both criteria aim to achieve a similar goal, the values returned by each are not directly comparable.
To rapidly create a random Latin hypercube design of any size, generateRandomDesign() is recommended. This method is fast, but does not guarantee that the design is optimal.
To rapidly create Latin hypercube designs with a small number of samples (fewer than ~25) and variables (fewer than ~5), generateTranslationalPropagationDesign() is recommended. This method uses a deterministic algorithm that translates and propagates a "seed" design throughout the design space to generate a Latin hypercube design.
Finally, to optimize Latin hypercube designs with larger numbers of samples and variable, generateStochasticEvolutionaryDesign() is recommended. This approach randomly exchanges samples between columns in the design matrix and accepts new designs based on an evolving warming and cooling schedule. This method is slower than the other two methods, but generally leads to better designs. This algorithm requires many evaluations of the design score, so it is recommended to use the "phi_p" distance criterion, which approximates "maximin", but is much faster.
| OpenSim::LatinHypercubeDesign::LatinHypercubeDesign | ( | ) |
| OpenSim::LatinHypercubeDesign::LatinHypercubeDesign | ( | const LatinHypercubeDesign & | ) |
| OpenSim::LatinHypercubeDesign::LatinHypercubeDesign | ( | LatinHypercubeDesign && | ) |
| double OpenSim::LatinHypercubeDesign::evaluateDesign | ( | const SimTK::Matrix & | design | ) | const |
Evaluate the distance between samples in the Latin hypercube design according to the distance criterion specified by the user.
The "maximin" criterion returns a negative value since it is a maximization criterion, while the "phi_p" criterion returns a positive value since it is a minimization criterion.
| SimTK::Matrix OpenSim::LatinHypercubeDesign::generateRandomDesign | ( | int | iterations = 100 | ) | const |
Generate a Latin hypercube design based on the best design score from multiple random designs.
Use the 'iterations' parameter to specify the number of random designs to evaluate before selecting a design.
| SimTK::Matrix OpenSim::LatinHypercubeDesign::generateStochasticEvolutionaryDesign | ( | int | iterations = 10, |
| const SimTK::Matrix & | initialDesign = {} |
||
| ) | const |
Generate a Latin hypercube design based on the enhanced stochastic evolutionary algorithm from Jin et al.
(2005). Use the 'iterations' parameter to specify the number of iterations to run the algorithm (i.e., the number of outer loop iterations). The number of inner loop iterations and column exchanges are determined automatically based on the number of samples in the design. Optionally, an initial design can be provided to the algorithm using the 'initialDesign' parameter.
| SimTK::Matrix OpenSim::LatinHypercubeDesign::generateTranslationalPropagationDesign | ( | int | numSeedPoints = -1 | ) | const |
Generate a Latin hypercube design based on the translational propagation algorithm from Viana et al.
(2009). Use the 'numSeedPoints' parameter to specify the number of seed points to use in the algorithm. The default behavior (numSeedPoints = -1) will iterate through several designs starting with seeds with number of seed points between 5% and 25% of the total number of samples in the design.
| const std::string& OpenSim::LatinHypercubeDesign::getDistanceCriterion | ( | ) | const |
The criterion used to evaluate the distance between samples in the Latin hypercube design ("maximin" or "phi_p").
| int OpenSim::LatinHypercubeDesign::getNumSamples | ( | ) | const |
The number of samples in the Latin hypercube design (i.e., the number of rows in the design matrix).
| int OpenSim::LatinHypercubeDesign::getNumVariables | ( | ) | const |
The number of variables in the Latin hypercube design (i.e., the number of columns in the design matrix).
| int OpenSim::LatinHypercubeDesign::getPhiPDistanceExponent | ( | ) | const |
The exponent used to evaluate the "phi_p" distance criterion.
This can be any non-zero integer, but should be set to a relatively large value (e.g., 50) to ensure that the criterion sufficiently approximates the "maximin" criterion.
| LatinHypercubeDesign& OpenSim::LatinHypercubeDesign::operator= | ( | const LatinHypercubeDesign & | ) |
| LatinHypercubeDesign& OpenSim::LatinHypercubeDesign::operator= | ( | LatinHypercubeDesign && | ) |
| void OpenSim::LatinHypercubeDesign::setDistanceCriterion | ( | std::string | distanceCriterion | ) |
The criterion used to evaluate the distance between samples in the Latin hypercube design ("maximin" or "phi_p").
| void OpenSim::LatinHypercubeDesign::setNumSamples | ( | int | numSamples | ) |
The number of samples in the Latin hypercube design (i.e., the number of rows in the design matrix).
| void OpenSim::LatinHypercubeDesign::setNumVariables | ( | int | numVariables | ) |
The number of variables in the Latin hypercube design (i.e., the number of columns in the design matrix).
| void OpenSim::LatinHypercubeDesign::setPhiPDistanceExponent | ( | int | exponent | ) |
The exponent used to evaluate the "phi_p" distance criterion.
This can be any non-zero integer, but should be set to a relatively large value (e.g., 50) to ensure that the criterion sufficiently approximates the "maximin" criterion.
1.8.14