************************************ :mod:`core` -- core of Nodes system. ************************************ .. module:: nodes.core :platform: Any :synopsis: Core of Nodes system. .. moduleauthor:: Alexander Sedov :class:`Node` - base class for all Nodes. ----------------------------------------- .. class:: Node(inputs, outputs[, iweights[, oweights]][, sysname=None]) Base class for all Nodes. It provides all necessary interface except Globnet I/O interface. Constructor arguments: :param inputs, outputs: lists of Node inputs/outputs. :type inputs, outputs: lists of :class:`Synaps` class instances .. note:: They **won't** be automatically :meth:`Synaps.bind` to self. :param iweights, oweights: input/output weights. Defaults to ones. :type iweights, oweights: lists/:mod:`NumPy` arrays :param sysname: Node system name. It is only for identification; there may be multiple Nodes with same sysnames. :type sysname: string .. rubric:: Methods .. method:: init_prepare() Finishing initialization. This may be overriden, but you *should* call the original version of :meth:`init_prepare` in your own definition. .. method:: check_valid() Checking after initialization. Originally, checks topology of Node to match its :attr:`__shape__`. When overriding this method, it is recommended to call original version from your implementation. .. method:: touch() Touch Node for calculations. Whenever called, causes :meth:`touch` es of whole net. It is recursion-safe, because (un)sets :attr:`free` flag to False, and, if it's already False, returns immediately. .. method:: compute() Cause computation of Node. Causes :meth:`compute` ings of all Nodes that connected with *direct arcs*; so it is recursion-safe because of topological reasons. .. note:: :meth:`touch` and :meth:`compute` will return immediately if :attr:`calculated` flag is set. Both methods also sets this flag after execution, so you need :meth:`reset` ting of Node before second use. .. method:: prepare_calc() fix_calc() Preparing for/fixing calculations. Originally, both methods do nothing, so they may be overriden in subclass. .. method:: preprocess() postprocess() Preprocessing and postprocessing calculations. These methods are called just before and after :meth:`calculate`. Originally, resets respectively :attr:`output` and :attr:`input` arrays. It is not necessary at all, but I am tired of stubs :) .. method:: get_values() put_values() mul_iweights() mul_oweights() These are internal methods called from :meth:`touch` and :meth:`compute`. Please don't override they if you don't know what are you doing. .. method:: calculate() Calculation function. It is not function, it is operator in mathematical sense of these words, because it maps :attr:`input` array (vector) to :attr:`output` one. Actually, it must work with only these two arrays but there are no restrictions. Originally, it raises :exc:`NotImplementedError` so it *should* be overriden in subclasses. .. method:: teach() Teaching function. Originally, it calls :meth:`forth_propagation`. .. method:: forth_propagation() back_propagation(targets) Two teaching methods in all meanings of this word. :meth:`forth_propagation` is my own concept, consists of three parts: *habituating*; *keyfactors search*; *merging*. *Habituating* is getting used to similar values and ajusting an absolute value of weight. *Keyfactors search* uses an interesting "bell-like" *keyness function*, reaches maximal value around argument ``1``. Weights ajusts with keyness of value. *Merging* uses *unstability* of persistent weight: weight ``0`` is very stable, weight ``0.5`` is very unstable. It also uses *force factor* of temporary weight; it reaches maximal value with argument ``0``. With this two factors, new persistent weight is computed. :meth:`back_propagation` is described in many articles. It uses *targets* argument to compute error and back-propagate it. It requires :meth:`calc_drv` method that calculates derivative of function (ha! function that maps ``input[i]`` to ``output[i]``). :meth:`calc_drv` is called with ``output[i]`` argument. :param targets: targets of output values. :type targets: list/array .. method:: calc_drv(value) Derivative calculation. See :meth:`back_propagate`. :param value: value of f(x). :returns: value of f'(x). :type value: any numerical type .. method:: add_input (synaps) add_output(synaps) Dynamically adding inputs/outputs to Node. These methods simply modify respectively :attr:`inputs` and :attr:`outputs` and add new weights. Then they recall :meth:`init_prepare` and, of course, :meth:`check_valid` to finish work. :param synaps: synaps to be added. :type synaps: :class:`Synaps` instance .. method:: reset() Resets internal flags (:attr:`free` and :attr:`calculated`) to defaults. .. method:: __str__() If :attr:`sysname` is not-null, returns it. Otherwise, returns unique name consists of :attr:`__class__.__name__` and :func:`id`. .. rubric:: Class Attributes .. attribute:: __itemtype__ Type of array items. It may be any type that :mod:`NumPy` accepts. By default, it is :data:`float32` .. attribute:: __shape__ = iN, oN Shape of Node. Should be a tuple of two values with below meanings: - If value is None, it means "any number of items". - If value is greater than zero, it means "exactly N items". - If value is less than zero, it means "``abs(N)`` items or greater". - If value equals to zero, it means "no items." :cvar __itemtype__: type of array items. :type __itemtype__: :mod:`NumPy` accepted type. :cvar __shape__: shape of Node. :type shape: two-tuple of number-or-:data:`None` s. .. rubric:: Instance attributes. .. attribute:: inputs outputs Input/output arcs(synapses) to other Nodes. .. attribute:: input_weights output_weights Input/output weights. These are :mod:`NumPy` arrays. .. attribute:: sysname System name of Node. See :samp:`constructor` .. attribute:: iN oN Number of inputs/outputs. :func:`len` takes a time [#]_, so I decided to make these attributes. .. attribute:: ivalues ovalues :mod:`NumPy` arrays that contain input (raw) values and output values. These attributes are *external*; they are with what :class:`Synaps` es and :meth:`forth_propagation` work. .. attribute:: input output :mod:`NumPy` arrays that contain input and output values. These attributes are *internal*; they are with what :meth:`calculate` works. .. attribute:: ilog olog :mod:`NumPy` arrays that contain "logs' of values. These attributes are used in :meth:`forth_propagate` to keep "old", or "usual", values. .. attribute:: N Number of teachings. Used in :meth:`forth_propagation` as stability (inertness). .. attribute:: free calculated Internal flags that indicates if Node is free and if it is already computed/touched. Used by :meth:`touch` and :meth:`compute`. .. attribute:: layer Read-only property means *distance* to closest *input Node*. If there are no inputs, returns -1. :ivar inputs, outputs: inputs/outputs of Node. :type inputs, outputs: lists of :class:`Synaps` class instances. :ivar input_weights, output_weights: input/output weights of Node. :type input_weights, output_weights: :mod:`NumPy` arrays. :ivar sysname: system name of Node. :type sysname: string. :ivar iN, oN: number of Node inputs/outputs. :type iN, oN: integers. :ivar ivalues, ovalues: external input/output values. :type ivalues, ovalues: :mod:`NumPy` arrays. :ivar input, output: internal inut/output values. :type input, output: :mod:`NumPy` arrays. :ivar ilog, olog: input/output values logs. :type ilog, olog: :mod:`NumPy` arrays. :ivar N: number of self-teachings. :type N: integer. :ivar free: flag shows if Node is free. :type free: bool. :ivar calculated: flag shows if Node is already calculated. :type calculated: bool. :ivar layer: distance from closest :ref:`input Node `. :type layer: property returns integer. Synaps - basic Synaps interfaces. --------------------------------- .. class:: Synaps .. rubric:: Methods .. method:: bind(innode, inindex, outnode, outindex) Binds Synaps to Nodes instances. :param innode, outnode: input and output Node. :type innode, outnode: :class:`Node` instances. :param inindex, outindex: Indices to which bind self. if index==-1, it means "append"; in that case :class:`Synaps` will use :meth:`add_input`/:meth:`add_output` method of :class:`Node`. :type inindex, outindex: integers. .. method:: pullin() passin() Pulls/passes value thru self without touching :attr:`outnode`. .. note:: *Pass* means *make value setup* with possible call of :meth:`compute` method (only if synaps/arc is *direct*) *Pull* means *make value setup* with possible call of :meth:`touch` method, if it is necessary. *Make value setup* means assign ``outnode.ivalues[outindex]=innode.ovalues[inindex]``. .. note:: :meth:`passin` and :meth:`pullin` are for use from :attr:`outnode` (its :meth:`get_values` method). .. method:: pullout() passout() Pulls/passes value thru self without touching :attr:`innode`. .. note:: :meth:`passout` and :meth:`pullout` are for use from :attr:`innode` (its :meth:`put_values` method). .. method:: pullthru() passthru() Pulls/passes value thru self. .. note:: :meth:`pullthru` and :meth:`passthru` are for *external* use (from :class:`Glob`, by example). .. rubric:: Instance Attributes .. attribute:: innode outnode Input/output Node of Synaps. See :meth:`bind`. .. attribute:: inindex outindex Input/output indices. See :meth:`bind`. .. attribute:: bound Flag shows if Synaps is already bound. .. attribute:: direction Read-only property means *direction* of arc. if :attr:`direction` greater than zero, arc/synaps is *direct*; otherwise, it is *indirect*. :ivar innode, outnode: input and output Node. :type innode, outnode: :class:`Node` instances. :ivar inindex, outindex: input/output indices. :type inindex, outindex: integers. :ivar bound: flag shows if Synaps is already bound. :type bound: bool. :ivar direction: direction of Synaps (difference between Nodes' layers). :type direction: property returns integer. Exceptions and other data ------------------------- .. exception:: Stop Internal exception that may be raised in :meth:`calculate` and will be catched in :meth:`touch` and :meth:`compute` methods. It simply stops calculation and any propagation. .. data:: flotype default floating point type of array items. :var flotype: =float32 .. rubric:: Footnotes .. [#] These attributes are/were used by :meth:`forth_propagation`, the most slow method.