import ParameterChecker from 'Artistoo/src/hamiltonian/ParameterChecker.js'

public class | source

ParameterChecker

Class for checking if parameters are present in a conf object and are of the expected structure and type. This is not meant for usage from outside the package, but you can use it when you are building your own constraints and want to specify the required parameters.

Example:

// Add this above your constraint class
import ParameterChecker from "./ParameterChecker.js"

// from inside the confChecker() function of your constraint:
let checker = new ParameterChecker( this.conf, this.C )

// Most parameters have a standard structure and value type;
// you can check them like this:
checker.confCheckParameter( "MY_PARAMETER", "KindMatrix", "Number" ) // see Adhesion
checker.confCheckParameter( "MY_PARAMETER_2", "KindArray", "NonNegative" )

// Or you can just check their presence and do a custom check:
checker.confCheckPresenceOf( "MY_WEIRD_PARAMETER" )
if( !myCondition ){
	throw( "Some error because MY_WEIRD_PARAMETER does not fulfill myCondition!" )
}

Constructor Summary

Public Constructor
public	constructor(conf: object, C: CPM) The constructor of the ParameterChecker takes a configuration object.

Member Summary

Public Members
public	C: CPM The attached CPM.
public	conf: object The configuration object to check parameters in

Method Summary

Public Methods
public	confCheckParameter(name: string, structure: string, valuetype: string, values: string[]) Check if a parameter exists and is defined, has the right structure, and if all its elements are of the correct type.
public	confCheckPresenceOf(name: string) Method to check if a parameter of a given name is present in the conf object supplied to the constraint, and if it is defined.
public	confCheckStructure(p: SingleValue \| KindArray \| KindMatrix, name: string, structure: string) Method for checking if the parameter has the right structure.
public	confCheckStructureKindArray(p: KindArray, name: string) Check if a parameter has a KindArray structure.
public	confCheckStructureKindMatrix(p: KindMatrix, name: string) Checker if a parameter has a KindMatrix structure.
public	confCheckStructureSingle(p: SingleValue, name: string) Check if a parameter consists of a single value (rather than an object or array), which can be a string, number, or boolean.
public	isCoordinate(v: number): boolean Check if a value is a coordinate in the dimensions of the current grid.

Private Methods
private	confCheckCellKinds(n_default: number): number Helper function.
private	confCheckValueType(p: anything, name: string, structure: string, valuetype: string, values: string[]) Check if the elements of a given parameter are of the right type.
private	isBoolean(v: number): boolean Check if a value is of type 'boolean'.
private	isNonNegative(v: number): boolean Check if a value is of type 'number' and non-negative.
private	isNumber(v: number): boolean Check if a value is of type 'number'.
private	isProbability(v: number): boolean Check if a value is of type 'number' and between 0 and 1.
private	isString(v: number, values: string[]): boolean Check if a value is of type 'string' and has one of a set of predefined values.

Public Constructors

public constructor(conf: object, C: CPM) source

The constructor of the ParameterChecker takes a configuration object.

Params:

Name	Type	Attribute	Description
conf	object		configuration settings as supplied to a constraint, containing the relevant parameters.
C	CPM		the attached CPM.

Public Members

public C: CPM source

The attached CPM. This is used to check if parameter array lengths match the number of cellkinds

public conf: object source

The configuration object to check parameters in

Public Methods

public confCheckParameter(name: string, structure: string, valuetype: string, values: string[]) source

Check if a parameter exists and is defined, has the right structure, and if all its elements are of the correct type. Throw an error if any of these do not hold.

Params:

Name	Type	Attribute	Description
name	string		parameter name used for any error messages.
structure	string		parameter structure, which must be one of "SingleValue", "KindArray", or "KindMatrix".
valuetype	string		type of value, which must be one of "Number", "NonNegative", "Probability", "String", or "Boolean".
values	string[]	optional default: []	predefined specific options for the value. If left empty, this is ignored.

Example:

// from inside the confChecker() function of your constraint:
let checker = new ParameterChecker( this.conf, this.C )

checker.confCheckParameter( "MY_PARAMETER", "KindMatrix", "Number" ) // see Adhesion
checker.confCheckParameter( "MY_PARAMETER_2", "KindArray", "NonNegative" )

public confCheckPresenceOf(name: string) source

Method to check if a parameter of a given name is present in the conf object supplied to the constraint, and if it is defined. Throws an error if this is not the case.

Params:

Name	Type	Attribute	Description
name	string		the name of the parameter, which should be present as a key in the object.

Example:

let conf = { MY_PARAMETER : "something" }
// This works, because  MY_PARAMETER is present in conf
let checker = new ParameterChecker( conf, myCPM )
checker.confCheckPresenceOf( "MY_PARAMETER" )

// There will be an error if MY_PARAMETER is absent/undefined:
conf = {}
checker = new ParameterChecker( conf, myCPM )
checker.confCheckPresenceOf( "MY_PARAMETER" )
conf = { MY_PARAMETER : "undefined" }
checker = new ParameterChecker( conf, myCPM )
checker.confCheckPresenceOf( "MY_PARAMETER" )

public confCheckStructure(p: SingleValue | KindArray | KindMatrix, name: string, structure: string) source

Method for checking if the parameter has the right structure. Throws an error message if the parameter does not have this structure.

It internally uses one of the following functions, depending on the structure argument: confCheckStructureSingle, confCheckStructureKindArray, or confCheckStructureKindMatrix.

Params:

Name	Type	Attribute	Description
p	SingleValue \| KindArray \| KindMatrix		the parameter to check the structure of
name	string		the name of this parameter in the conf object, used for the error message.
structure	string		parameter structure, which must be one of "SingleValue", "KindArray", or "KindMatrix".

Example:

// My own configuration object
let conf = {
P1 : true,
	P2 : [0,2],
	P3 : [-1,2,4],
	P4 : [[1,2],[1,2]]
}
// C is a CPM which has 2 cellkinds including background:
let checker = new ParameterChecker( conf, C )
// These checks work out fine:
checker.confCheckStructure( conf["P1"],"P1","SingleValue")
checker.confCheckStructure( conf["P2"],"P2","KindArray")
checker.confCheckStructure( conf["P4"],"P4","KindMatrix")

// These checks throw an error:
checker.confCheckStructure( conf["P1"],"P1","KindArray") // not an array
checker.confCheckStructure( conf["P2"],"P3","KindArray") // too long

public confCheckStructureKindArray(p: KindArray, name: string) source

Check if a parameter has a KindArray structure.

Params:

Name	Type	Attribute	Description
p	KindArray		the parameter to check
name	string		the name of this parameter in the conf object, used for the error message if p is not a KindArray.

Example:

// C is a CPM which has 2 cellkinds including background:
let checker = new ParameterChecker( conf, C )
let p1 = [1,1], p2 = ["hi","hi"], p3 = "hi", p4 = [1,2,3]
// Nothing happens when parameters are indeed arrays of length 2
// (regardless of what type of array)
checker.confCheckStructureKindArray( p1, "MY_PARAMETER" )
checker.confCheckStructureKindArray( p2, "MY_PARAMETER" )

// You'll get an error when p is no array, or when 
// its length doesn't match the number of cellkinds:
checker.confCheckStructureSingle( p3, "MY_PARAMETER" )
checker.confCheckStructureSingle( p4, "MY_PARAMETER" )

public confCheckStructureKindMatrix(p: KindMatrix, name: string) source

Checker if a parameter has a KindMatrix structure. If this is not the case, the method throws an error.

Params:

Name	Type	Attribute	Description
p	KindMatrix		the parameter to check
name	string		the name of this parameter in the conf object, used for the error message if p is not a KindMatrix.

Example:

// C is a CPM which has 2 cellkinds including background:
let checker = new ParameterChecker( conf, C )
let p1 = [[1,1],[1,1]], p2 = [["a","a"],["a","a"]] 
// Nothing happens when parameters are indeed arrays of length 2
// with sub-arrays of length 2 (regardless of what is in the elements)
checker.confCheckStructureKindArray( p1, "MY_PARAMETER" ) //OK
checker.confCheckStructureKindArray( p2, "MY_PARAMETER" ) //OK

// You'll get an error when p is no array, or when 
// its length doesn't match the number of cellkinds:
let p3 = 1, p4 = [1,2,3], p5 = [[1,2],[1,2],[1,2]]
checker.confCheckStructureSingle( p3, "MY_PARAMETER" ) //error
checker.confCheckStructureSingle( p4, "MY_PARAMETER" ) //error
checker.confCheckStructureSingle( p5, "MY_PARAMETER" ) //error

public confCheckStructureSingle(p: SingleValue, name: string) source

Check if a parameter consists of a single value (rather than an object or array), which can be a string, number, or boolean.

Params:

Name	Type	Attribute	Description
p	SingleValue		the parameter to check, which must be a single string/number/boolean value.
name	string		the name of this parameter in the conf object, used for the error message if p is not a single value.

Example:

let checker = new ParameterChecker( conf, C )
let p1 = true, p2 = 1, p3 = "hi", p4 = [1,2]
// Nothing happens for parameters of type SingleValue:
checker.confCheckStructureSingle( p1, "MY_PARAMETER" )
checker.confCheckStructureSingle( p2, "MY_PARAMETER" )
checker.confCheckStructureSingle( p3, "MY_PARAMETER" )

// This will throw an error because p4 is an array.
checker.confCheckStructureSingle( p4, "MY_PARAMETER" )

public isCoordinate(v: number): boolean source

Check if a value is a coordinate in the dimensions of the current grid.

Params:

Name	Type	Attribute	Description
v	number		value to check.

Return:

boolean

is v a coordinate of the right dimensions?

Private Methods

private confCheckCellKinds(n_default: number): number source

Helper function. Some parameters need to be specified for each CellKind, so to check those we first need to know the number of cellkinds on the CPM. This number is retrieved from the CPM or added to it if it isn't there yet.

Params:

Name	Type	Attribute	Description
n_default	number		a number of cellkinds (including background), which is used to set the number of cellkinds in the CPM if it isn't there yet.

Return:

number

the number of non-background cellkinds as cached in the CPM.

private confCheckValueType(p: anything, name: string, structure: string, valuetype: string, values: string[]) source

Check if the elements of a given parameter are of the right type. It throws an error if this is not the case.

Params:

Name	Type	Attribute	Description
p	anything		parameter to check.
name	string		parameter name used for any error messages.
structure	string		parameter structure, which must be one of "SingleValue", "KindArray", or "KindMatrix".
valuetype	string		type of value, which must be one of "Number", "NonNegative", "Probability", "String", or "Boolean".
values	string[]		predefined specific options for the value. If left empty, this is ignored.

private isBoolean(v: number): boolean source

Check if a value is of type 'boolean'.

Params:

Name	Type	Attribute	Description
v	number		value to check.

Return:

boolean

is v a boolean?

Example:

this.isBoolean( true ) // true
this.isBoolean( [true,false] ) // false
this.isBoolean( "hello world" ) // true

private isNonNegative(v: number): boolean source

Check if a value is of type 'number' and non-negative.

Params:

Name	Type	Attribute	Description
v	number		value to check.

Return:

boolean

is v a non-negative number?

Example:

this.isNonNegative( -1 ) // false
this.isNonNegative( 0.5 ) // true
this.isNumber( true ) // false
this.isNumber( [1,2 ] ) // false
this.isNumber( "hello world" ) // false

private isNumber(v: number): boolean source

Check if a value is of type 'number'.

Params:

Name	Type	Attribute	Description
v	number		value to check.

Return:

boolean

is v a number?

Example:

this.isNumber( -1 ) // true
this.isNumber( 0.5 ) // true
this.isNumber( true ) // false
this.isNumber( [1,2 ] ) // false
this.isNumber( "hello world" ) // false

private isProbability(v: number): boolean source

Check if a value is of type 'number' and between 0 and 1.

Params:

Name	Type	Attribute	Description
v	number		value to check.

Return:

boolean

is v a number between 0 and 1?

Example:

this.isProbability( -1 ) // false
this.isProbability( 0.5 ) // true
this.isProbability( true ) // false
this.isProbability( [1,2 ] ) // false
this.isProbability( "hello world" ) // false

private isString(v: number, values: string[]): boolean source

Check if a value is of type 'string' and has one of a set of predefined values.

Params:

Name	Type	Attribute	Description
v	number		value to check.
values	string[]	optional default: []	possible values. If left empty, any string is considered OK.

Return:

boolean

is v a string and does it match one of the predefined values?

Example:

this.isString( true ) // false
this.isString( ["a","b"] ) // false
this.isString( "hello world" ) // true