TINC
Toolkit for Interactive Computation
|
The ParameterSpace class contains a set of ParameterSpaceDimensions and organizes access to them. More...
#include <ParameterSpace.hpp>
Public Member Functions | |
ParameterSpace (std::string id=std::string()) | |
~ParameterSpace () | |
ParameterSpace (const ParameterSpace &other)=delete | |
ParameterSpace & | operator= (const ParameterSpace &other)=delete |
ParameterSpaceDimension * | getDimension (std::string name, std::string group="") |
Get a registered ParameterSpaceDimension by name. More... | |
ParameterSpaceDimension * | newDimension (std::string name, ParameterSpaceDimension::RepresentationType type=ParameterSpaceDimension::VALUE, ParameterType parameterType=ParameterType::PARAMETER_FLOAT, std::string group="") |
create and register a new dimension for this parameter space More... | |
ParameterSpaceDimension * | registerDimension (std::shared_ptr< ParameterSpaceDimension > &dimension, al::Socket *src=nullptr) |
Register an existing dimension with the parameter space. More... | |
void | removeDimension (std::string name, std::string group="", bool invoked=false, al::Socket *src=nullptr) |
remove dimension from list of registered dimensions More... | |
std::vector< ParameterSpaceDimension * > | getDimensions () |
get list of currently registered dimensions More... | |
std::vector< std::string > | runningPaths (std::vector< std::string > fixedDimensions=std::vector< std::string >()) |
Returns all the paths that are used by the whole parameter space. More... | |
std::string | getCurrentRelativeRunPath () |
Get relative filesystem path for current parameter values. More... | |
std::string | getCommonId (std::vector< std::string > dimNames={}, std::map< std::string, size_t > indices={}) |
Resolve common id for dimensions. More... | |
std::vector< std::string > | getDimensionNames () |
Returns the names of all dimensions. More... | |
bool | isFilesystemDimension (std::string dimensionName) |
Determines if dimensionName is a dimension that affeects the filesystem. More... | |
void | clear () |
removes all dimensions from parameter space More... | |
bool | incrementIndices (std::map< std::string, size_t > ¤tIndices) |
increment to next index from index array More... | |
bool | runProcess (Processor &processor, const std::map< std::string, al::VariantValue > &args={}, const std::map< std::string, al::VariantValue > &dependencies={}, bool recompute=false) |
run a Processor with information and caching from the parameter space More... | |
void | sweep (Processor &processor, std::vector< std::string > dimensionNames={}, std::map< std::string, al::VariantValue > dependencies={}, bool recompute=false) |
sweep the parameter space across all or specified dimensions More... | |
void | sweepAsync (Processor &processor, std::vector< std::string > dimensionNames={}, std::map< std::string, al::VariantValue > dependencies={}, bool recompute=false, int numThreads=1) |
Run a parameter sweep asynchronously (non-blocking) More... | |
void | stopSweep () |
Interrupts an asynchronous parameter sweep after current computation is done. More... | |
bool | createDataDirectories () |
Create necessary filesystem directories to be populated by data. More... | |
bool | cleanDataDirectories () |
Prepare data directoires, leaving them empty if they had any contents. More... | |
bool | removeDataDirectories () |
Remove all directories related to this parameter space. More... | |
bool | readFromNetCDF (std::string ncFile="parameter_space.nc") |
Load parameter space dimensions from disk file. More... | |
bool | writeToNetCDF (std::string fileName="parameter_space.nc") |
write parameter space dimensions to netCDF file. More... | |
bool | readDimensionsInNetCDFFile (std::string filename, std::vector< std::shared_ptr< ParameterSpaceDimension >> &newDimensions) |
Read dimensions from parameter space netcdf file. More... | |
void | setRootPath (std::string rootPath) |
Set the parameter space's root path. More... | |
std::string | getRootPath () |
Get root path for the parameter space. More... | |
void | setCurrentPathTemplate (std::string pathTemplate) |
Set path template. More... | |
std::string | getCurrentPathTemplate () |
Return current path template. More... | |
std::string | resolveTemplate (std::string fileTemplate, std::map< std::string, size_t > indeces={}) |
resolve filename template according to current parameter values More... | |
void | enableCache (std::string cachePath) |
Enable caching for the parameter space. More... | |
CacheEntry | cacheEntryForProcessor (Processor &processor) |
void | disableCache () |
Disable caching for the parameter space. More... | |
std::shared_ptr< CacheManager > | getCacheManager () |
get CacheManager object More... | |
void | print (std::ostream &stream=std::cout) |
std::string | getId () |
get this object's id More... | |
void | setId (std::string id) |
set this object's id More... | |
std::string | getDocumentation () const |
void | setDocumentation (const std::string &documentation) |
Static Public Member Functions | |
static std::string | getCommonId (std::vector< ParameterSpaceDimension * > dimensions, std::map< ParameterSpaceDimension *, size_t > indices) |
static std::string | resolveTemplate (std::string fileTemplate, std::vector< ParameterSpaceDimension * > dimensions, std::map< ParameterSpaceDimension *, size_t > indecesOverride={}) |
Public Attributes | |
std::map< std::string, std::string > | parameterNameMap |
map names provided to getDimension() to internal data names More... | |
std::function< std::string(std::map< std::string, size_t >, ParameterSpace *)> | generateRelativeRunPath |
function that generated relative paths according to current values. More... | |
std::function< void(double progress)> | onSweepProcess |
onSweepProcess is called after a sample completes processing as part of a sweep More... | |
std::function< void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps)> | onValueChange |
std::function< void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps, al::Socket *src)> | onDimensionRegister |
std::function< void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps, bool invoked, al::Socket *src)> | onDimensionRemove |
std::function< void(al::Socket *src)> | modified = [](al::Socket * ) {} |
Protected Member Functions | |
void | updateParameterSpace (ParameterSpaceDimension *ps) |
update current position to value in dimension ps More... | |
bool | executeProcess (Processor &processor, bool recompute) |
Protected Attributes | |
std::vector< std::shared_ptr< ParameterSpaceDimension > > | mDimensions |
std::vector< std::shared_ptr< ParameterSpaceDimension > > | mDimensionsOwned |
std::string | mCurrentPathTemplate |
Stores template to generate current path using resolveFilename() More... | |
std::vector< std::shared_ptr< std::thread > > | mAsyncProcessingThreads |
std::shared_ptr< ParameterSpace > | mAsyncPSCopy |
bool | mSweepRunning {false} |
std::map< std::string, std::string > | mSpecialDirs |
std::shared_ptr< CacheManager > | mCacheManager |
std::string | mRootPath |
Filesystem root path for parameter space. More... | |
std::string | mId |
std::string | mDocumentation |
Friends | |
class | TincProtocol |
The ParameterSpace class contains a set of ParameterSpaceDimensions and organizes access to them.
Parameter spaces can be linked to specific directories in the file system. This can be useful to locate data according to paramter values. For example when the data is a result of a parameter sweep that generated multiple directories. See setCurrentPathTemplate() and generateRelativeRunPath for more information.
Definition at line 59 of file ParameterSpace.hpp.
|
inline |
Definition at line 63 of file ParameterSpace.hpp.
tinc::ParameterSpace::~ParameterSpace | ( | ) |
|
delete |
CacheEntry tinc::ParameterSpace::cacheEntryForProcessor | ( | Processor & | processor | ) |
bool tinc::ParameterSpace::cleanDataDirectories | ( | ) |
Prepare data directoires, leaving them empty if they had any contents.
Use this function with extreme care, as it can be very destructive!!
void tinc::ParameterSpace::clear | ( | ) |
removes all dimensions from parameter space
bool tinc::ParameterSpace::createDataDirectories | ( | ) |
Create necessary filesystem directories to be populated by data.
void tinc::ParameterSpace::disableCache | ( | ) |
Disable caching for the parameter space.
void tinc::ParameterSpace::enableCache | ( | std::string | cachePath | ) |
Enable caching for the parameter space.
cachePath | path relative to root path |
Caching will be used when calling runProcess() and sweep() You should use cachePath as a relative path to rootPath
|
protected |
|
inline |
get CacheManager object
Use with care, as some functionality within CacheManager will not propagate correctly if set from object. As a rule of thumb use this object to query rather than configure the cache manager.
Definition at line 400 of file ParameterSpace.hpp.
|
static |
std::string tinc::ParameterSpace::getCommonId | ( | std::vector< std::string > | dimNames = {} , |
std::map< std::string, size_t > | indices = {} |
||
) |
Resolve common id for dimensions.
dims | |
indeces | map containing override values |
When dimensions have the same value mapped to multiple ids, the id can be resolved through the combination with other dimensions
|
inline |
std::string tinc::ParameterSpace::getCurrentRelativeRunPath | ( | ) |
Get relative filesystem path for current parameter values.
Generated according to generateRelativePath()
ParameterSpaceDimension* tinc::ParameterSpace::getDimension | ( | std::string | name, |
std::string | group = "" |
||
) |
Get a registered ParameterSpaceDimension by name.
name | |
group |
std::vector<std::string> tinc::ParameterSpace::getDimensionNames | ( | ) |
Returns the names of all dimensions.
std::vector<ParameterSpaceDimension *> tinc::ParameterSpace::getDimensions | ( | ) |
get list of currently registered dimensions
|
inherited |
|
inherited |
get this object's id
std::string tinc::ParameterSpace::getRootPath | ( | ) |
Get root path for the parameter space.
Path constructed thgouth the path template and the generateRelativeRunPath() should be relative to this path.
bool tinc::ParameterSpace::incrementIndices | ( | std::map< std::string, size_t > & | currentIndices | ) |
increment to next index from index array
currentIndices |
bool tinc::ParameterSpace::isFilesystemDimension | ( | std::string | dimensionName | ) |
Determines if dimensionName is a dimension that affeects the filesystem.
dimensionName |
ParameterSpaceDimension* tinc::ParameterSpace::newDimension | ( | std::string | name, |
ParameterSpaceDimension::RepresentationType | type = ParameterSpaceDimension::VALUE , |
||
ParameterType | parameterType = ParameterType::PARAMETER_FLOAT , |
||
std::string | group = "" |
||
) |
create and register a new dimension for this parameter space
name | dimension name |
type | representation type for the value |
parameterType | data type and behavior of parameter |
|
delete |
void tinc::ParameterSpace::print | ( | std::ostream & | stream = std::cout | ) |
bool tinc::ParameterSpace::readDimensionsInNetCDFFile | ( | std::string | filename, |
std::vector< std::shared_ptr< ParameterSpaceDimension >> & | newDimensions | ||
) |
Read dimensions from parameter space netcdf file.
filename | ||
[out] | newDimensions |
bool tinc::ParameterSpace::readFromNetCDF | ( | std::string | ncFile = "parameter_space.nc" | ) |
Load parameter space dimensions from disk file.
ncFile |
The file is loaded relative to 'rootPath'. Dimension found in the file are added to the current parameter space if a dimension with that name already exists, it is replaced.
ParameterSpaceDimension* tinc::ParameterSpace::registerDimension | ( | std::shared_ptr< ParameterSpaceDimension > & | dimension, |
al::Socket * | src = nullptr |
||
) |
Register an existing dimension with the parameter space.
dimension | dimension to register |
src | original socket that message came from * / |
If the dimension was already registered, the data from the incoming dimension is copied to the existing dimension and the existing dimension is returned. You must always use the returned shared_ptr instead of the shared_ptr passed
bool tinc::ParameterSpace::removeDataDirectories | ( | ) |
Remove all directories related to this parameter space.
Use this function with extreme care, as it can be very destructive!!
void tinc::ParameterSpace::removeDimension | ( | std::string | name, |
std::string | group = "" , |
||
bool | invoked = false , |
||
al::Socket * | src = nullptr |
||
) |
remove dimension from list of registered dimensions
name | dimension name |
group | dimension group |
invoked | true only if called by TincProtocol's removeParameter |
src | original socket that message came from |
std::string tinc::ParameterSpace::resolveTemplate | ( | std::string | fileTemplate, |
std::map< std::string, size_t > | indeces = {} |
||
) |
resolve filename template according to current parameter values
fileTemplate | |
indeces | map of indeces that override current values. |
You can use %% to delimit dimension names, e.g. "value_%%ParameterValue%%" where %ParameterValue%% will be replaced by the current value (in the correct representation as ID, VALUE or INDEX) of the dimension whose id is "ParameterValue". You can specify a different representation than the one set for the ParameterSpaceDimension by adding it following a ':'. For example: "value_%%ParameterValue:INDEX%%" will replace "%%ParameterValue:INDEX%%" with the current index for ParameterValue. For parameters that have mutiple ids for the same value, you can specify any muber of parameters separated by commas. the function getCommonId() will be called. For example, for %param1,param2%% the common id for the their current values will be inserted. Any representation type (ID, VALUE, INDEX) is ignored, as only ids are used. Using this method can be useful as it can avoid having to define a custom generateRelativeRunPath() function
|
static |
std::vector<std::string> tinc::ParameterSpace::runningPaths | ( | std::vector< std::string > | fixedDimensions = std::vector< std::string >() | ) |
Returns all the paths that are used by the whole parameter space.
fixedDimensions | only use paths for the current values of these dimensions |
bool tinc::ParameterSpace::runProcess | ( | Processor & | processor, |
const std::map< std::string, al::VariantValue > & | args = {} , |
||
const std::map< std::string, al::VariantValue > & | dependencies = {} , |
||
bool | recompute = false |
||
) |
run a Processor with information and caching from the parameter space
processor | processor to run |
args | additional or override arguments to pass to the processor |
dependencies | processor to run |
recompute | force recompute if true |
The args map can provide additional configuration arguments to the processor or can replace the current value of a parameter with that name
|
inline |
Set path template.
pathTemplate | By default, the generateRelativePath() function will use this template to generate the path, but this path might be ignored if it is not used in the new generateRelativeRunPath() function. You must either call this function or set a generateRelativeRunPath function to have the parameter space linked to a location in the filesystem. |
See resolveFilename() for information on how the template is resolved.
Definition at line 312 of file ParameterSpace.hpp.
|
inherited |
|
inherited |
set this object's id
void tinc::ParameterSpace::setRootPath | ( | std::string | rootPath | ) |
Set the parameter space's root path.
rootPath |
void tinc::ParameterSpace::stopSweep | ( | ) |
Interrupts an asynchronous parameter sweep after current computation is done.
void tinc::ParameterSpace::sweep | ( | Processor & | processor, |
std::vector< std::string > | dimensionNames = {} , |
||
std::map< std::string, al::VariantValue > | dependencies = {} , |
||
bool | recompute = false |
||
) |
sweep the parameter space across all or specified dimensions
processor | processor to sweep with parameter space |
dimensionNames | names of dimensions to sweep, all if empty |
recompute | force recompute if true |
void tinc::ParameterSpace::sweepAsync | ( | Processor & | processor, |
std::vector< std::string > | dimensionNames = {} , |
||
std::map< std::string, al::VariantValue > | dependencies = {} , |
||
bool | recompute = false , |
||
int | numThreads = 1 |
||
) |
Run a parameter sweep asynchronously (non-blocking)
This function's parameters are identical to sweep()
|
protected |
update current position to value in dimension ps
ps | This function checks if new dataset directory needs a reload of parameter_space.nc and processes the parameter space changes |
bool tinc::ParameterSpace::writeToNetCDF | ( | std::string | fileName = "parameter_space.nc" | ) |
write parameter space dimensions to netCDF file.
fileName |
|
friend |
Definition at line 60 of file ParameterSpace.hpp.
std::function<std::string(std::map<std::string, size_t>, ParameterSpace *)> tinc::ParameterSpace::generateRelativeRunPath |
function that generated relative paths according to current values.
You must either set this function or use setCurrentPathTemplate() to have the parameter space linked to a location in the filesystem. Only override this function if using a path template is insufficient. If this function is replaced, the path template will have noeffect unless it is specifically used in the new function.
This function should always return the path ending with a drectory separator.
Definition at line 335 of file ParameterSpace.hpp.
|
protected |
Definition at line 492 of file ParameterSpace.hpp.
|
protected |
Definition at line 493 of file ParameterSpace.hpp.
|
protected |
Definition at line 500 of file ParameterSpace.hpp.
|
protected |
Stores template to generate current path using resolveFilename()
Definition at line 490 of file ParameterSpace.hpp.
|
protected |
This callback is called when dimension metadata has changed or a dimension is added. When a dimension is new, the new dimension has not yet been added to the parameter space.
Definition at line 485 of file ParameterSpace.hpp.
|
protected |
Definition at line 487 of file ParameterSpace.hpp.
|
protectedinherited |
Definition at line 69 of file IdObject.hpp.
|
protectedinherited |
Definition at line 68 of file IdObject.hpp.
|
inherited |
Definition at line 65 of file IdObject.hpp.
|
protected |
Filesystem root path for parameter space.
This root path is where the root parameter space should be localted and should contain all data directories
Definition at line 508 of file ParameterSpace.hpp.
|
protected |
Definition at line 498 of file ParameterSpace.hpp.
|
protected |
Definition at line 495 of file ParameterSpace.hpp.
std::function<void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps, al::Socket *src)> tinc::ParameterSpace::onDimensionRegister |
This callback is called when dimension metadata has changed or a dimension is added. When a dimension is new, the new dimension has not yet been added to the parameter space.
If dimension was not registered correctly we will be in an inconsistent state, and user will be warned. assert will fail to trigger crash on debug builds.
Definition at line 440 of file ParameterSpace.hpp.
std::function<void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps, bool invoked, al::Socket *src)> tinc::ParameterSpace::onDimensionRemove |
This callback is called when dimension is removed
Definition at line 453 of file ParameterSpace.hpp.
std::function<void(double progress)> tinc::ParameterSpace::onSweepProcess |
onSweepProcess is called after a sample completes processing as part of a sweep
Definition at line 345 of file ParameterSpace.hpp.
std::function<void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps)> tinc::ParameterSpace::onValueChange |
@brief callback when the value in any particular dimension changes. You can get the new and previous values through changedDimension. The values are contained within the parameterMeta() object and you will need to cast to the appropriate type, for example:
You should use this callback whenever you need to know the specific dimension that has changed. For this reason, you should not update processor configurations from here, as this function will not be called, except when a particular dimension has changed.
Definition at line 425 of file ParameterSpace.hpp.
std::map<std::string, std::string> tinc::ParameterSpace::parameterNameMap |
map names provided to getDimension() to internal data names
You can also use this map to display user friendly names when displaying parameters. Changing this is not thread safe.
Definition at line 296 of file ParameterSpace.hpp.