API documentation

The documentation of the C++ code.

C++ core classes

Python pyDtOO classes

The documentation of the pyDtOO package.

class pyDtOO.dtClusteredSingletonState.dtClusteredSingletonState[source]

Manage database.

Connection to the database that holds at least fitness and objective values. Objectives (inputs, parameters, degrees of freedom, …) are the values that are changed during optimization to improve the fitness (result value, …) of the problem. Every individual has an ID and a state as integer and str, respectively. This class also stores optional (additional) data for each individual. A data value is in the simplest case a scalar value as integer or float. But it can be also a float array or a dict.

The class stores all data in the directory DATADIR. Fitness value, objective value, ID and state are stored in the files fitness.*, objective.*, id.* and state.*, respectively. If additional data is used the files are named according to the ADDDATA array. The data in DATADIR are divided in chunks of 1000 lines per file.

PREFIX

Prefix for the state label. The default is ‘A1’

Type:: str

CASE

Label of the simulation case. The default is ‘’

Type:: str

LOCKDIR

Directory of the lock directory. The default is dtGod().LockPath()

Type:: dtDirectory

PIDDIR

Directory of the PIDDIR. The default is ‘./runPid’

Type:: str

DATADIR

Directory to store the data. The default is ‘./runData’

Type:: str

NPROC

Number of processes. The default is 1

Type:: int

SIMSH

Name of the simulation script. The default is ‘’

Type:: str

ADDDATA

Array of additional (optional) data. The default is []

Type:: List[str]

ADDDATADEF

Default values for additional data. The default is []

Type:: List[ Union[ List[float], int, dict] ]

PROB

Problem class. The default is None

Type:: Any

id_

ID of individual

Type:: float

state_

State of individual

Type:: str

Examples

Add additional values for each individual

>>> dtClusteredSingletonState.ADDDATA = [
...   'dict',
...   'float',
...   'int',
...   'np-float-arr',
...   'np-int-arr',
...   'str',
... ]
>>> dtClusteredSingletonState.ADDDATADEF = [
...   {'key' : 0.0},
...   1.0,
...   2,
...   np.full(3, 5.0),
...   np.full(3, -5),
...   'test',
... ]

Create first individual

>>> dtClusteredSingletonState(
...   defObj=[0.0,0.0,],
...   defFit=[0.0,0.0,]
... )
<dtClusteredSingletonState.dtClusteredSingletonState object at ...>

Access individual by id

>>> cSS = dtClusteredSingletonState(1)

Check if data exactly matches the ADDDATADEF list

>>> for i in dtClusteredSingletonState.ADDDATA:
...   print(
...     cSS(i)
...     ==
...     dtClusteredSingletonState.ADDDATADEF[
...       dtClusteredSingletonState.ADDDATA.index(i)
...     ]
...   )
True
True
True
[ True  True  True]
[ True  True  True]
True

Write new data

>>> cSS = dtClusteredSingletonState(1)
>>> cSS.update('fitness', 1.0)
>>> cSS.update('objective', [1.0,2.0])
>>> cSS.update('dict', {'float' : 1.0, 'str' : 'myStr'})

Read default data from individual

>>> cSS.id()
1
>>> cSS.state()
'A1_1'
>>> cSS.objective()
array([1., 2.])
>>> cSS.fitness()
array([1.])

Read additional data as str

>>> cSS.read('float')
'1.e+00'
>>> cSS.read('dict')
'{"float": 1.0, "str": "myStr"}'

Read additional data with specified type

>>> cSS.readFloatArray('float')
array([1.])
>>> cSS.readFloat('float')
1.0
>>> cSS.readArray('np-int-arr', int)
array([-5, -5, -5])
>>> cSS.read('np-int-arr')
'-5 -5 -5'
>>> cSS.readDict('dict')
{'float': 1.0, 'str': 'myStr'}

Check data again; some checks have to fail, because the data was updated

>>> for i in dtClusteredSingletonState.ADDDATA:
...   print("=> %s" % i)
...   print(cSS(i))
...   print(
...     cSS(i)
...     ==
...     dtClusteredSingletonState.ADDDATADEF[
...       dtClusteredSingletonState.ADDDATA.index(i)
...     ]
...   )
=> dict
{'float': 1.0, 'str': 'myStr'}
False
=> float
1.0
True
=> int
2
True
=> np-float-arr
[5. 5. 5.]
[ True  True  True]
=> np-int-arr
[-5 -5 -5]
[ True  True  True]
=> str
test
True

Check type of elements in the arrays

Note

Numpy versions smaller than 2.0.0 return int and float instead of np.int64 and float64, respectively.

>>> cSS('np-int-arr')[0]
np.int64(-5)

>>> cSS('np-float-arr')[0]
np.float64(5.0)

Stored scalar integer values should be returned as int for both versions

>>> cSS('int')
2

static clear(remove: bool = False) → None

Clear database.

Parameters:: remove (bool) – Flag to clean directory, too.
Return type:: None

static currentMaxId() → int[source]

Get current maximum ID stored in database.

Raises:: ValueError – If file index < 0.
Returns:: Maximum ID.
Return type:: int

Examples

>>> dtClusteredSingletonState.clear(True)
>>> a = dtClusteredSingletonState()
>>> b = dtClusteredSingletonState()
>>> dtClusteredSingletonState.currentMaxId()
2

static fileIndex(id: int) → int[source]

Get file index of individual’s data.

Parameters:: id (int) – ID of individual.
Returns:: File index.
Return type:: int

fitness() → numpy.ndarray[source]

Read fitness for current individual.

Returns:: Fitness.
Return type:: numpy.ndarray

static formatToWrite(value: float | int | dict | numpy.array) → str[source]

Converts value to str.

Parameters:: value (Union[float, int, dict, np.array]) – Value to convert.
Returns:: Converted value.
Return type:: str

Examples

>>> dtClusteredSingletonState.formatToWrite(1.0)
'1.e+00'
>>> dtClusteredSingletonState.formatToWrite(1)
'1'
>>> dtClusteredSingletonState.formatToWrite('word')
'word'
>>> dtClusteredSingletonState.formatToWrite(
...   {'str' : 'word', 'float' : 1.0}
... )
'{"str": "word", "float": 1.0}'
>>> dtClusteredSingletonState.formatToWrite(np.full(2,1.0))
'1.e+00 1.e+00'
>>> try:
...   dtClusteredSingletonState.formatToWrite(['a', 'b',])
... except ValueError as e:
...   print(e)
Unknown datatype.
>>> class testclass:
...   pass
>>> try:
...   dtClusteredSingletonState.formatToWrite(testclass)
... except ValueError as e:
...   print(e)
Unknown datatype.

static fullAddRead(addFileV: List, addDtypeV: List = []) → List[numpy.ndarray]

Read additional data of all individuals.

Parameters:

addFileV (np.ndarray) – List of additional data to read.
addDtypeV (np.ndarray) – List of additional dtype.

Return type:

List

Examples

>>> dtClusteredSingletonState.clear(True)
>>> dtClusteredSingletonState.ADDDATA = ['float', 'dict']
>>> dtClusteredSingletonState.ADDDATADEF = [1.0, {'test' : 2.0},]
>>> a = dtClusteredSingletonState()
>>> b = dtClusteredSingletonState()
>>> A = dtClusteredSingletonState.fullAddRead(['float', 'dict'])
>>> A['float']
array([1., 1.])
>>> A['dict']
array([{'test': 2.0}, {'test': 2.0}], dtype=object)
>>> A['dict'][0]['test']
2.0

static fullAddReadDict(addFile: str, maxFileIndex: int) → numpy.ndarray[source]

Read additional dicts of all individuals.

Parameters:

addFile (str) – File name of additional dict.
maxFileIndex (int) – Maximum file index.

Returns:

Additional dicts for all individuals.

Return type:

np.ndarray

static fullRead() → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Read IDs, objective values and fitness values of all individuals.

Parameters:

addFile (Union[ None, List[str] ], optional) – List of additional files to read. The default is None.
addDtype (Union[float, int, dict], optional) – dtype of additional values. The default is float.

Returns:

Union[ – Tuple[np.ndarray, np.ndarray, np.ndarray], Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]
] – Tuple of IDs, objective and fitness values. If addFile is not None, then the return tuple is extended by additional array.

Examples

>>> dtClusteredSingletonState.clear(True)
>>> a = dtClusteredSingletonState(defObj=[1.0, 1.0],defFit=[1.5,1.5])
>>> b = dtClusteredSingletonState(defObj=[2.0, 2.0],defFit=[2.5, 2.5])
>>> I,O,F = dtClusteredSingletonState.fullRead()
>>> for i,o,f in zip(I,O,F):
...   i
...   o
...   f
np.int64(1)
array([1., 1.])
array([1.5, 1.5])
np.int64(2)
array([2., 2.])
array([2.5, 2.5])

hasDirectory() → bool[source]

Check if individual’s case directory exist

Return type:: bool

id() → int[source]

Get individual’s ID.

Raises:: ValueError – If ID < 0.
Returns:: ID.
Return type:: int

objective() → numpy.ndarray[source]

Read objective for current individual.

Returns:: Objective.
Return type:: numpy.ndarray

static oneD(arr: numpy.ndarray) → numpy.ndarray[source]

Convert array’s shape to one-dimensional numpy.ndarray.

Parameters:: arr (numpy.ndarray) – Array.
Returns:: Converted array.
Return type:: numpy.ndarray

read(fName: str) → str[source]

Read data of fName for current individual.

Parameters:: fName (str) – Label of data.
Returns:: Value.
Return type:: str

readArray(fName: str, dtype: float | int | str) → numpy.ndarray[source]

Read data of fName for current individual and return as array.

Parameters:: fName (str) – Label of data.
Returns:: Converted value.
Return type:: numpy.ndarray

readDict(fName: str) → dict[source]

Read data of fName for current individual and return as dict.

Parameters:: fName (str) – Label of data.
Returns:: Converted value.
Return type:: dict

readFloat(fName: str) → float[source]

Read data of fName for current individual and return as float.

Parameters:: fName (str) – Label of data.
Returns:: Converted value.
Return type:: float

readFloatArray(fName: str) → numpy.ndarray[source]

Read data of fName for current individual and return as float array.

Parameters:: fName (str) – Label of data.
Returns:: Converted value.
Return type:: numpy.ndarray

static readIdFromObjective(obj: numpy.ndarray) → int[source]

Returns ID of individual with objective obj.

Parameters:: obj (numpy.ndarray) – Objective.
Returns:: ID.
Return type:: int
Warns:: Warning if difference in objective values >0.1.

Examples

>>> dtClusteredSingletonState.clear(True)
>>> a = dtClusteredSingletonState(defObj=[1.0, 1.0],defFit=[2.0])
>>> a.objective()
array([1., 1.])
>>> b = dtClusteredSingletonState(defObj=[2.0, 2.0],defFit=[2.0])
>>> b.objective()
array([2., 2.])
>>> dtClusteredSingletonState.readIdFromObjective(np.array(a.objective()))
1
>>> dtClusteredSingletonState.readIdFromObjective(np.array(b.objective()))
2

readInt(fName: str) → int[source]

Read data of fName for current individual and return as integer.

Parameters:: fName (str) – Label of data.
Returns:: Converted value.
Return type:: int

readIntArray(fName: str) → numpy.ndarray[source]

Read data of fName for current individual and return as int array.

Parameters:: fName (str) – Label of data.
Returns:: Converted value.
Return type:: numpy.ndarray

state() → str[source]

Get individual’s state.

Raises:: ValueError – If ID < 0.
Returns:: State.
Return type:: str

static twoD(arr: numpy.ndarray) → numpy.ndarray[source]

Convert array’s shape to two-dimensional numpy.ndarray.

Parameters:: arr (numpy.ndarray) – Array.
Returns:: Converted array.
Return type:: numpy.ndarray

update(fileName: str, value: float | int | dict | numpy.array) → None

Write data of fName for current individual.

Parameters:

fileName (str) – Label of data.
value (Union[float, int, dict, np.array]) – Value.

Return type:

None