From 2f097a9cc8e64f644364051c1d12001f7186ef17 Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Wed, 2 Oct 2019 16:50:01 +0200 Subject: documentation --- lib/functions.py | 33 ++++++++++++++++----------------- lib/modular_arithmetic.py | 45 ++++++++++++++++++++++++++++++--------------- 2 files changed, 46 insertions(+), 32 deletions(-) (limited to 'lib') diff --git a/lib/functions.py b/lib/functions.py index 76be562..87fb2f0 100644 --- a/lib/functions.py +++ b/lib/functions.py @@ -14,9 +14,7 @@ arg_support_enabled = True def powerset(iterable): """ - Calculate powerset of `iterable` elements. - - Returns an iterable containing one tuple for each powerset element. + Return powerset of `iterable` elements. Example: `powerset([1, 2])` -> `[(), (1), (2), (1, 2)]` """ @@ -39,15 +37,14 @@ class ParamFunction: (-> single float as model input) are used. However, n-dimensional functions (-> list of float as model input) are also supported. - :param param_function: regression function. Must have the signature - (reg_param, model_param) -> float. + :param param_function: regression function (reg_param, model_param) -> float. reg_param is a list of regression variable values, model_param is the model input value (float). - Example: lambda rp, mp: rp[0] + rp[1] * mp + Example: `lambda rp, mp: rp[0] + rp[1] * mp` :param validation_function: function used to check whether param_function is defined for a given model_param. Signature: model_param -> bool - Example: lambda mp: mp > 0 + Example: `lambda mp: mp > 0` :param num_vars: How many regression variables are used by this function, i.e., the length of param_function's reg_param argument. """ @@ -55,32 +52,33 @@ class ParamFunction: self._validation_function = validation_function self._num_variables = num_vars - def is_valid(self, arg): + def is_valid(self, arg: float) -> bool: """ Check whether the regression function is defined for the given argument. - Returns bool. + :param arg: argument (e.g. model parameter) to check for + :returns: True iff the function is defined for `arg` """ return self._validation_function(arg) - def eval(self, param, args): + def eval(self, param: list, arg: float) -> float: """ Evaluate regression function. :param param: regression variable values (list of float) :param arg: model input (float) - :return: regression function output (float) + :returns: regression function output (float) """ - return self._param_function(param, args) + return self._param_function(param, arg) - def error_function(self, P, X, y): + def error_function(self, P: list, X: float, y: float) -> float: """ Calculate model error. :param P: regression variables as returned by optimization (list of float) :param X: model input (float) :param y: expected model output / ground truth for model input (float) - :return: Deviation between model output and ground truth (float) + :returns: Deviation between model output and ground truth (float) """ return self._param_function(P, X) - y @@ -89,16 +87,17 @@ class NormalizationFunction: Wrapper for parameter normalization functions used in YAML PTA/DFA models. """ - def __init__(self, function_str): + def __init__(self, function_str: str): """ Create a new normalization function from `function_str`. - :param function_str: Function string. Signature: (param) -> float + :param function_str: Function string. Must use the single argument + `param` and return a float. """ self._function_str = function_str self._function = eval('lambda param: ' + function_str) - def eval(self, param_value): + def eval(self, param_value: float) -> float: """ Evaluate the normalization function and return its output. diff --git a/lib/modular_arithmetic.py b/lib/modular_arithmetic.py index baf979a..0a69b79 100644 --- a/lib/modular_arithmetic.py +++ b/lib/modular_arithmetic.py @@ -2,11 +2,20 @@ # Licensed under GFDL 1.2 https://www.gnu.org/licenses/old-licenses/fdl-1.2.html import operator import functools - + @functools.total_ordering class Mod: + """A class for modular arithmetic, useful to simulate behaviour of uint8 and other limited data types. + + Does not support negative values, therefore it cannot be used to emulate signed integers. + + Overloads a==b, ab, a+b, a-b, a*b, a**b, and -a + + :param val: stored integer value + Param mod: modulus + """ __slots__ = ['val','mod'] - + def __init__(self, val, mod): if isinstance(val, Mod): val = val.val @@ -16,13 +25,13 @@ class Mod: raise ValueError('Modulo must be positive integer') self.val = val % mod self.mod = mod - + def __repr__(self): return 'Mod({}, {})'.format(self.val, self.mod) - + def __int__(self): return self.val - + def __eq__(self, other): if isinstance(other, Mod): self.val == other.val @@ -30,7 +39,7 @@ class Mod: return self.val == other else: return NotImplemented - + def __lt__(self, other): if isinstance(other, Mod): return self.val < other.val @@ -38,25 +47,25 @@ class Mod: return self.val < other else: return NotImplemented - + def _check_operand(self, other): if not isinstance(other, (int, Mod)): raise TypeError('Only integer and Mod operands are supported') - + def __pow__(self, other): self._check_operand(other) # We use the built-in modular exponentiation function, this way we can avoid working with huge numbers. return __class__(pow(self.val, int(other), self.mod), self.mod) - + def __neg__(self): return Mod(self.mod - self.val, self.mod) - + def __pos__(self): return self # The unary plus operator does nothing. - + def __abs__(self): return self # The value is always kept non-negative, so the abs function should do nothing. - + # Helper functions to build common operands based on a template. # They need to be implemented as functions for the closures to work properly. def _make_op(opname): @@ -65,14 +74,14 @@ def _make_op(opname): self._check_operand(other) return Mod(op_fun(self.val, int(other)) % self.mod, self.mod) return op - + def _make_reflected_op(opname): op_fun = getattr(operator, opname) def op(self, other): self._check_operand(other) return Mod(op_fun(int(other), self.val) % self.mod, self.mod) return op - + # Build the actual operator overload methods based on the template. for opname, reflected_opname in [('__add__', '__radd__'), ('__sub__', '__rsub__'), ('__mul__', '__rmul__')]: setattr(Mod, opname, _make_op(opname)) @@ -115,7 +124,13 @@ class Uint64(Mod): return 'Uint64({})'.format(self.val) -def simulate_int_type(int_type: str): +def simulate_int_type(int_type: str) -> Mod: + """ + Return `Mod` subclass for given `int_type` + + :param int_type: uint8_t / uint16_t / uint32_t / uint64_t + :returns: `Mod` subclass, e.g. Uint8 + """ if int_type == 'uint8_t': return Uint8 if int_type == 'uint16_t': -- cgit v1.2.3