McParameter and its collection

Base class to handle Verilog-AMS modelcard parameters.

Each parameter has a type, unit, boundaries and invalid values (excludes), this is taken care of here. Usually the user has a group of parameters stored in a Collection. The collection exposes methods to manage the group safely. In generall here many copies are used, in the exposes methods always deepcopies are returned and set to the collection. This reduces crazy errors, but also need to be handled with care.

Additionally parameters can be compared, they are considered equal, if they have the same name and value. Also collections can be compared, they are equal, if they have the same parameters and all parameters are equal.

Finally the classes here also add some pretty printing and loading and saving using pickle.

class DMT.core.mc_parameter.McParameter(name: str, value: float | int | None = None, minval: float | int | None = None, maxval: float | int | None = None, value_type: ~typing.Type = <class 'float'>, inc_min: bool = True, inc_max: bool = True, exclude: ~typing.List[float | int] | float | int | None = None, group: str = '', unit: ~pint.registry.Unit = <Unit('dimensionless')>, description: str = '')[source]

Bases: object

Objects of this class represent a model card parameter. If you want to store many of them, see McParameterCollection class.

Parameters:

namestr: Name of the parameter.
valueUnion[float, int, None]: Value for the parameter. Can also be a other Parameter, then all attributes are copied.
unitpint.unit: Unit of the python Pint package.
minvalUnion[float, int, None]: Minimum boundary value of the parameter.
maxvalUnion[float, int, None]: Maximum boundary value of the parameter.
groupstr: Display is sorted by groups.
value_typeType[Union[int, float]]: The type of the value.
inc_minbool: If True, value==min is allowed.
inc_maxbool: If True, value==max is allowed.
excludeOptional[List[Union[float, int]]]: List of values that are excluded as a valid value for value. E.g. if min=-1, max=1, sometimes you might want to exclude 0.
descriptionstr: Description of the parameter

Attributes:

_valueUnion[float, int, None]: The value of this parameter.
namestr: The name of the parameter.
inc_minbool: If True, value==min is allowed.
inc_maxbool: If True, value==max is allowed.
minUnion[float, int]: Return The minimum boundary as an array of length one.
maxUnion[float, int]: Return The minimum boundary as an array of length one.
excludeOptional[List[Union[float, int]]]: Return the type of the value.
val_typeType[Union[int, float]]: Return the type of the value.
descriptionstr: Description of the parameter

Methods

check_bounds(value)	Check wheather or not value is within the bounds of this parameter.
_set_forced( value)	Force setting the value. ATTENTION: When used, the boundaries may be set to inf!
dict_json()	Returns a compact formatted json dump of this parameter
load_json(cls, name, value, __McParameter__, min, max, type, inc_min, inc_max, exclude, group, unit, description)	Creates a McParameter from a dictionary obtained by a json.load.

check_bounds(value: float | int)[source]

Check wheather the value parameter is inside the boundaries defined by self.min and self.max.

Parameters:

valueint or float or convertable to float: Value that shall be checked.

Returns:

valueint or float: Checked value

dict_json() → dict[str, float | int | str | bool | None | List[float | int]][source]: Returns a compact formatted json dump of this parameter

property exclude[source]: Return the type of the value.

classmethod load_json(name: str, value: float | int, __McParameter__: float | str, min: float | int | None = None, max: float | int | None = None, type: str = '', inc_min: bool = True, inc_max: bool = True, exclude: List[float | int] | None = None, group: str = '', unit: str | Unit = '', description: str = '')[source]: Creates a McParameter from a dictionary obtained by a json.load.

property max: float | int[source]: Return The minimum boundary as an array of length one.

property min: float | int[source]: Return The minimum boundary as an array of length one.

property val_type[source]: Return the type of the value.

property value: float | int | None[source]: Returns the value.

class DMT.core.mc_parameter.McParameterCollection(possible_groups: Dict[str, str] | None = None, __McParameterCollection__: Version | str | float = Version(major=1, minor=0, patch=1, prerelease=None, build=None), **kwargs)[source]

Bases: object

This parameter collection has properties which as a single parameter. This way a group of parameters and a single parameter can be treated equally.

Parameters:

possible_groupsdict[str, str], optional: Dictionary of possible groups in this collection, saved as Description: GroupName, by default None
__McParameterCollection__Union[VersionInfo, str, float], optional: Version of the given creation parameters, by default SEMVER_MCPARAMETER_Collection_CURRENT

Raises:

NotImplementedError: Raised when the given version is unknown and hence the

Attributes:

paraslist: Return the parameters with updated values.

add(paras, index=None, update=True)[source]: Add a parameter to self. This is only allowed, if the parameter name is not already known to the collection.

dump_json(file_path, **kwargs)[source]

Writes itself and the parameters in the collection to a file.

To manipulate what is written to the file, change :py:method::DMT.core.mc_parameter.McParameterCollection.info_json() and inherited methods

dumps_json(**kwargs)[source]

eq_paras(other, to_terminal=False)[source]: Compares the parameters in two McParameterCollections or subclasses

Returns a McParameterCollection with copies of all given parameter names.

Parameters:

parametersstr, iterable(str) or McParameterCollection

Returns:

mcard_collectionMcParameterCollection

Raises:

KeyError: If the para was not in self.

get_circuit(use_build_in=False, topology=None, **kwargs) → Circuit[source]

Here the modelcard defines it’s default simulation circuit.

Parameters:

use_build_in{False, True}, optional: Creates a circtui the modelcard using the build-in model
topologyoptional: If a model has multiple standard circuits, use the topology to differentiate between them..

get_values(parameters)[source]

Returns a list of the values of parameters.

Returns:

{name:value}: A dict with the name of the parameter as key and value as value.

Raises:

KeyError: If the para was not in self.

property group[source]: Returns all groups of the parameters in the collection as a set

info_json(**_kwargs)[source]: Returns a dict with serializeable content for the json file to create. Add the info about the concrete subclass to create here!

iter_alphabetical()[source]: Returns an iterator on parameters sorted alphabetically by name

classmethod load(path)[source]

Load an object from a pickle file.

Parameters:

pathstr: Path to the file to load.

Returns:

McParameterCollection

classmethod load_json(file_path: str | Path, directory_va_file: str | Path | None = None, ignore_checksum: bool = False) → McParameterCollection[source]

Loads the json file, creates the McParameterCollection (or inherited) and adds the McParameters.

Parameters:

file_pathUnion[str, Path]: Path to the json.
directory_va_fileUnion[str, Path, None], optional: If a relative path to a va_file is set in the modelcard, pass the absolute path to the start folder here, by default None. This can be used to load old json modelcards from before saving the full code with the parameters.
ignore_checksumbool, optional: When the code is saved compressed, a checksum is saved with it. If you want to ignore the checksum set this to true, by default False

Returns:

McParameterCollection: The loaded collection

Raises:

IOError: If the collection dictionary is not found in the json file.

classmethod loads_json(s: str, directory_va_file: str | Path | None = None, ignore_checksum: bool = False) → McParameterCollection[source]

Loads the json string, creates the McParameterCollection (or inherited) and adds the McParameters.

Parameters:

file_pathUnion[str, Path]: string with the json.
directory_va_fileUnion[str, Path, None], optional: If a relative path to a va_file is set in the modelcard, pass the absolute path to the start folder here, by default None. This can be used to load old json modelcards from before saving the full code with the parameters.
ignore_checksumbool, optional: When the code is saved compressed, a checksum is saved with it. If you want to ignore the checksum set this to true, by default False

Returns:

McParameterCollection: The loaded collection

Raises:

IOError: If the collection dictionary is not found in the json file.

property max[source]: All maximal values of this group

property min[source]: All minimal values of this group

property name[source]: Returns all names of the parameters in the collection

property paras[source]: Return the parameters with updated values.

print_parameters(paras=None, line_break='')[source]

Just some pretty printing

Parameters:

paramlist[str], optional: List of parameter names to print, if not given, all children are returned!
line_breakstr, optional: Is added after each parameter, can be used as line breaks

Returns:

str: String with all parameters.

print_tex(pretext='The final modelcard is summarized in the table below:')[source]: Prints a modelcard as a tex table using PyLaTeX

print_to_file(path_to_file, line_break='', create_dir=False)[source]

Prints the parameters into a file. Uses print_parameters() to obtain the string to print.

Parameters:

path_to_filestr: Path to the file to write. ‘.txt’ is added automatically.
line_breakstr, optionally: Is added after each parameter, can be used as line breaks
create_dir{False, True}, optionally: If true, the respective directory is created first.

remove(parameters)[source]

Removes the given parameter names from the parameter collection.

Parameters:

parametersstr, iterable(str), McParameter or McParameterCollection

set(parameters, update=True, force=False)[source]

Set existing paramaters in self.

Parameters:

parametersMcParameter or McParameterCollection: For each parameter, if it is found in self, it is removed and the given is added. If it is not found, a KeyError is raised.
update{True, False}, optional: If set to False, the values dict is not updated.
force{True, False}, optional: If set to True, the parameter is added if it did not exist.

Raises:

KeyError: If the para was not in self.

set_bounds(dict_parameters)[source]

Sets a dictionary of {‘name’:(min, max )} to the parameters in this collection

Parameters:

dict_parameters{str: (float64, float64)}: For each parameter, if it is found in self, the given values are set as minimum and maximum.

Raises:

KeyError: If the para was not in self.

set_values(dict_parameters, force=False, policy_missing='error')[source]

Sets a dictionary of {‘name’:value} to the parameters in this collection

Parameters:

dict_parameters{str: float64}: For each parameter, if it is found in self, the given value is set.
forcebool, optional: If True, values are force set.
policy_missing{“error”, “ignore”, “add”}, optional: The policy for missing parameters to set, defaults to “error”

Raises:

KeyError: If the para was not in self.

sort_paras()[source]: Sorts the parameters according to the groups.

to_kwargs()[source]

Returns itself as a dictionary fitting to unpack into a function call.

Returns:

dict: {name: value}

property unit[source]: Returns all units in the collection

update_paras()[source]: Writes back the values into the parameters.

update_values()[source]: Writes the parameter values into the values dict.

property value[source]: Returns all parameter values as a np.ndarray.