TINC
Toolkit for Interactive Computation
tinc::ParameterSpace Class Reference

The ParameterSpace class contains a set of ParameterSpaceDimensions and organizes access to them. More...

#include <ParameterSpace.hpp>

Inheritance diagram for tinc::ParameterSpace:
tinc::IdObject

Public Member Functions

 ParameterSpace (std::string id=std::string())
 
 ~ParameterSpace ()
 
 ParameterSpace (const ParameterSpace &other)=delete
 
ParameterSpaceoperator= (const ParameterSpace &other)=delete
 
ParameterSpaceDimensiongetDimension (std::string name, std::string group="")
 Get a registered ParameterSpaceDimension by name. More...
 
ParameterSpaceDimensionnewDimension (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...
 
ParameterSpaceDimensionregisterDimension (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 > &currentIndices)
 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< CacheManagergetCacheManager ()
 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< ParameterSpacemAsyncPSCopy
 
bool mSweepRunning {false}
 
std::map< std::string, std::string > mSpecialDirs
 
std::shared_ptr< CacheManagermCacheManager
 
std::string mRootPath
 Filesystem root path for parameter space. More...
 
std::string mId
 
std::string mDocumentation
 

Friends

class TincProtocol
 

Detailed Description

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.

Constructor & Destructor Documentation

◆ ParameterSpace() [1/2]

tinc::ParameterSpace::ParameterSpace ( std::string  id = std::string())
inline

Definition at line 63 of file ParameterSpace.hpp.

◆ ~ParameterSpace()

tinc::ParameterSpace::~ParameterSpace ( )

◆ ParameterSpace() [2/2]

tinc::ParameterSpace::ParameterSpace ( const ParameterSpace other)
delete

Member Function Documentation

◆ cacheEntryForProcessor()

CacheEntry tinc::ParameterSpace::cacheEntryForProcessor ( Processor processor)

◆ cleanDataDirectories()

bool tinc::ParameterSpace::cleanDataDirectories ( )

Prepare data directoires, leaving them empty if they had any contents.

Returns
true if all directories could be cleaned and recreated.

Use this function with extreme care, as it can be very destructive!!

◆ clear()

void tinc::ParameterSpace::clear ( )

removes all dimensions from parameter space

◆ createDataDirectories()

bool tinc::ParameterSpace::createDataDirectories ( )

Create necessary filesystem directories to be populated by data.

Returns
true if successfully created (or checked existence) of directories.

◆ disableCache()

void tinc::ParameterSpace::disableCache ( )

Disable caching for the parameter space.

◆ enableCache()

void tinc::ParameterSpace::enableCache ( std::string  cachePath)

Enable caching for the parameter space.

Parameters
cachePathpath relative to root path

Caching will be used when calling runProcess() and sweep() You should use cachePath as a relative path to rootPath

◆ executeProcess()

bool tinc::ParameterSpace::executeProcess ( Processor processor,
bool  recompute 
)
protected

◆ getCacheManager()

std::shared_ptr<CacheManager> tinc::ParameterSpace::getCacheManager ( )
inline

get CacheManager object

Returns
nullptr if cache not enabled

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.

◆ getCommonId() [1/2]

static std::string tinc::ParameterSpace::getCommonId ( std::vector< ParameterSpaceDimension * >  dimensions,
std::map< ParameterSpaceDimension *, size_t >  indices 
)
static

◆ getCommonId() [2/2]

std::string tinc::ParameterSpace::getCommonId ( std::vector< std::string >  dimNames = {},
std::map< std::string, size_t >  indices = {} 
)

Resolve common id for dimensions.

Parameters
dims
indecesmap containing override values
Returns

When dimensions have the same value mapped to multiple ids, the id can be resolved through the combination with other dimensions

◆ getCurrentPathTemplate()

std::string tinc::ParameterSpace::getCurrentPathTemplate ( )
inline

Return current path template.

Returns

Definition at line 320 of file ParameterSpace.hpp.

◆ getCurrentRelativeRunPath()

std::string tinc::ParameterSpace::getCurrentRelativeRunPath ( )

Get relative filesystem path for current parameter values.

Returns

Generated according to generateRelativePath()

◆ getDimension()

ParameterSpaceDimension* tinc::ParameterSpace::getDimension ( std::string  name,
std::string  group = "" 
)

Get a registered ParameterSpaceDimension by name.

Parameters
name
group
Returns
the dimension or nullptr if not found

◆ getDimensionNames()

std::vector<std::string> tinc::ParameterSpace::getDimensionNames ( )

Returns the names of all dimensions.

◆ getDimensions()

std::vector<ParameterSpaceDimension *> tinc::ParameterSpace::getDimensions ( )

get list of currently registered dimensions

◆ getDocumentation()

std::string tinc::IdObject::getDocumentation ( ) const
inherited

◆ getId()

std::string tinc::IdObject::getId ( )
inherited

get this object's id

◆ getRootPath()

std::string tinc::ParameterSpace::getRootPath ( )

Get root path for the parameter space.

Returns

Path constructed thgouth the path template and the generateRelativeRunPath() should be relative to this path.

◆ incrementIndices()

bool tinc::ParameterSpace::incrementIndices ( std::map< std::string, size_t > &  currentIndices)

increment to next index from index array

Parameters
currentIndices
Returns
true when no more indices to process

◆ isFilesystemDimension()

bool tinc::ParameterSpace::isFilesystemDimension ( std::string  dimensionName)

Determines if dimensionName is a dimension that affeects the filesystem.

Parameters
dimensionName
Returns
true if changes in dimension affect the filesystem paths

◆ newDimension()

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

Parameters
namedimension name
typerepresentation type for the value
parameterTypedata type and behavior of parameter
Returns
the newly created dimension.

◆ operator=()

ParameterSpace& tinc::ParameterSpace::operator= ( const ParameterSpace other)
delete

◆ print()

void tinc::ParameterSpace::print ( std::ostream &  stream = std::cout)

◆ readDimensionsInNetCDFFile()

bool tinc::ParameterSpace::readDimensionsInNetCDFFile ( std::string  filename,
std::vector< std::shared_ptr< ParameterSpaceDimension >> &  newDimensions 
)

Read dimensions from parameter space netcdf file.

Parameters
filename
[out]newDimensions
Returns
true if read was succesful

◆ readFromNetCDF()

bool tinc::ParameterSpace::readFromNetCDF ( std::string  ncFile = "parameter_space.nc")

Load parameter space dimensions from disk file.

Parameters
ncFile
Returns
true if reading was succesful

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.

◆ registerDimension()

ParameterSpaceDimension* tinc::ParameterSpace::registerDimension ( std::shared_ptr< ParameterSpaceDimension > &  dimension,
al::Socket *  src = nullptr 
)

Register an existing dimension with the parameter space.

Parameters
dimensiondimension to register
srcoriginal socket that message came from * /
Returns
pointer to the registered dimension

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

◆ removeDataDirectories()

bool tinc::ParameterSpace::removeDataDirectories ( )

Remove all directories related to this parameter space.

Returns
true if all directories could be cleaned and recreated.

Use this function with extreme care, as it can be very destructive!!

◆ removeDimension()

void tinc::ParameterSpace::removeDimension ( std::string  name,
std::string  group = "",
bool  invoked = false,
al::Socket *  src = nullptr 
)

remove dimension from list of registered dimensions

Parameters
namedimension name
groupdimension group
invokedtrue only if called by TincProtocol's removeParameter
srcoriginal socket that message came from

◆ resolveTemplate() [1/2]

std::string tinc::ParameterSpace::resolveTemplate ( std::string  fileTemplate,
std::map< std::string, size_t >  indeces = {} 
)

resolve filename template according to current parameter values

Parameters
fileTemplate
indecesmap of indeces that override current values.
Returns
resolved string

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

◆ resolveTemplate() [2/2]

static std::string tinc::ParameterSpace::resolveTemplate ( std::string  fileTemplate,
std::vector< ParameterSpaceDimension * >  dimensions,
std::map< ParameterSpaceDimension *, size_t >  indecesOverride = {} 
)
static

◆ runningPaths()

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.

Parameters
fixedDimensionsonly use paths for the current values of these dimensions

◆ runProcess()

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

Parameters
processorprocessor to run
argsadditional or override arguments to pass to the processor
dependenciesprocessor to run
recomputeforce recompute if true
Returns
return value from the processor

The args map can provide additional configuration arguments to the processor or can replace the current value of a parameter with that name

◆ setCurrentPathTemplate()

void tinc::ParameterSpace::setCurrentPathTemplate ( std::string  pathTemplate)
inline

Set path template.

Parameters
pathTemplateBy 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.

◆ setDocumentation()

void tinc::IdObject::setDocumentation ( const std::string &  documentation)
inherited

◆ setId()

void tinc::IdObject::setId ( std::string  id)
inherited

set this object's id

◆ setRootPath()

void tinc::ParameterSpace::setRootPath ( std::string  rootPath)

Set the parameter space's root path.

Parameters
rootPath

◆ stopSweep()

void tinc::ParameterSpace::stopSweep ( )

Interrupts an asynchronous parameter sweep after current computation is done.

◆ sweep()

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

Parameters
processorprocessor to sweep with parameter space
dimensionNamesnames of dimensions to sweep, all if empty
recomputeforce recompute if true

◆ sweepAsync()

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()

◆ updateParameterSpace()

void tinc::ParameterSpace::updateParameterSpace ( ParameterSpaceDimension ps)
protected

update current position to value in dimension ps

Parameters
psThis function checks if new dataset directory needs a reload of parameter_space.nc and processes the parameter space changes

◆ writeToNetCDF()

bool tinc::ParameterSpace::writeToNetCDF ( std::string  fileName = "parameter_space.nc")

write parameter space dimensions to netCDF file.

Parameters
fileName
Returns
true if writing was succesful

Friends And Related Function Documentation

◆ TincProtocol

friend class TincProtocol
friend

Definition at line 60 of file ParameterSpace.hpp.

Member Data Documentation

◆ generateRelativeRunPath

std::function<std::string(std::map<std::string, size_t>, ParameterSpace *)> tinc::ParameterSpace::generateRelativeRunPath
Initial value:
= [&](std::map<std::string, size_t> indices,
std::string path = ps->resolveTemplate(mCurrentPathTemplate, indices);
return al::File::conformDirectory(al::File::conformPathToOS(path));
}
ParameterSpace(std::string id=std::string())
std::string mCurrentPathTemplate
Stores template to generate current path using resolveFilename()

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.

◆ mAsyncProcessingThreads

std::vector<std::shared_ptr<std::thread> > tinc::ParameterSpace::mAsyncProcessingThreads
protected

Definition at line 492 of file ParameterSpace.hpp.

◆ mAsyncPSCopy

std::shared_ptr<ParameterSpace> tinc::ParameterSpace::mAsyncPSCopy
protected

Definition at line 493 of file ParameterSpace.hpp.

◆ mCacheManager

std::shared_ptr<CacheManager> tinc::ParameterSpace::mCacheManager
protected

Definition at line 500 of file ParameterSpace.hpp.

◆ mCurrentPathTemplate

std::string tinc::ParameterSpace::mCurrentPathTemplate
protected

Stores template to generate current path using resolveFilename()

Definition at line 490 of file ParameterSpace.hpp.

◆ mDimensions

std::vector<std::shared_ptr<ParameterSpaceDimension> > tinc::ParameterSpace::mDimensions
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.

◆ mDimensionsOwned

std::vector<std::shared_ptr<ParameterSpaceDimension> > tinc::ParameterSpace::mDimensionsOwned
protected

Definition at line 487 of file ParameterSpace.hpp.

◆ mDocumentation

std::string tinc::IdObject::mDocumentation
protectedinherited

Definition at line 69 of file IdObject.hpp.

◆ mId

std::string tinc::IdObject::mId
protectedinherited

Definition at line 68 of file IdObject.hpp.

◆ modified

std::function<void(al::Socket *src)> tinc::IdObject::modified = [](al::Socket * ) {}
inherited

Definition at line 65 of file IdObject.hpp.

◆ mRootPath

std::string tinc::ParameterSpace::mRootPath
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.

◆ mSpecialDirs

std::map<std::string, std::string> tinc::ParameterSpace::mSpecialDirs
protected

Definition at line 498 of file ParameterSpace.hpp.

◆ mSweepRunning

bool tinc::ParameterSpace::mSweepRunning {false}
protected

Definition at line 495 of file ParameterSpace.hpp.

◆ onDimensionRegister

std::function<void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps, al::Socket *src)> tinc::ParameterSpace::onDimensionRegister
Initial value:
= [](ParameterSpaceDimension *changedDimension,
ParameterSpace *ps, al::Socket *src = nullptr) {
(void)changedDimension;
(void)ps;
(void)src;
}

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.

◆ onDimensionRemove

std::function<void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps, bool invoked, al::Socket *src)> tinc::ParameterSpace::onDimensionRemove
Initial value:
= [](ParameterSpaceDimension *changedDimension,
ParameterSpace *ps, bool invoked = false,
al::Socket *src = nullptr) {}

This callback is called when dimension is removed

Definition at line 453 of file ParameterSpace.hpp.

◆ onSweepProcess

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.

◆ onValueChange

std::function<void(ParameterSpaceDimension *changedDimension, ParameterSpace *ps)> tinc::ParameterSpace::onValueChange
Initial value:
=
[](ParameterSpaceDimension *changedDimension, ParameterSpace *ps) {}
 @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:
float previous = dynamic_cast<Parameter
>(changedDimension->parameterMeta())
->getPrevious();
float newValue = dynamic_cast<Parameter
>(changedDimension->parameterMeta())
->get();

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.

◆ parameterNameMap

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.


The documentation for this class was generated from the following file: