module ieee1906-dot1-function { yang-version 1.1; namespace "urn:ieee:std:1906.1:yang:ieee1906-dot1-function"; prefix "ieee1906-dot1-function"; import ietf-yang-metadata { prefix md; } organization "P1906.1.1/D1.0 Draft Standard Data Model for Nanoscale Communication Systems Working Group"; contact "IEEE P1906.1.1 Working Group Chair: Stephen F. Bush Secretary: Guillaume Mantelet "; description "This experimental YANG module is an individual contribution, and does not represent a formally sanctioned YANG module by IEEE. Therefore, this YANG module will change in incompatible ways from its current revision to the formally published YANG module for IEEE 1906.1.1 Standard Data Model for Nanoscale Communication Systems. This module defines YANG as a programming language, making it an embodiment of an active networking language. The goal of this YANG function is to use a NETCONF server to remotely execute mathematical and logical functions. For example, one could imagine an interactive Python or MATLAB console exchanging function calls through XML RPCs. +--------------------+------------+----------------------------------------------+ | name | type | description | +--------------------+------------+----------------------------------------------+ | call | rpc | Used to call a function and retrive a result | | dynamic-programming| feature | This server is capable of YANG programming | | dynamic-assignment | feature | This server can assign to session variables | | function | grouping | A function to call with its positional args | | language | identity | The language that is supported by the server | | name | annotation | XML attribute to assign to session variables | | number | typedef | String representation of a number | | variable-name | typedef | String representation of a session variable | | variable | typedef | Number or unknowns defined by a name | +--------------------+------------+----------------------------------------------+ An RPC to explicitly call a function on the server is also defined. Defining function behavior is out of the scope of this YANG model. This YANG model only assumes that the functions to be used have consensus among the community. For example, a sum should be a well known function and the XML RPC function would look like: If previous RPC led to the NETCONF server storing a=2 and b=3 for a session, then: sum a b 1 and the NETCONF server would return: 6 . An annotation provides support for dynamic assignment for the current session, and provides 'hints' for the NETCONF server. Annotation offering naming means that 'name' can be used as an XML attribute for leaves, functions and containers: sum 2 3 is a hint so that the NETCONF server returns: 5 . Due ot the scope of this call, the assignment is lost when the result is returned. However, if 'c' had been previously defined as an assignment for this session, the function will assign the result to 'c', and 'c' can then be retrieved later. If ... c //myLeaf is of type instance-identifier or variableName ... the NETCONF server would return: ... 5 ... ."; revision 2020-02-14 { description "Initial version."; reference "P1906.1.1/D1.0 Draft Standard for Nanoscale and Molecular Communication Framework"; } feature dynamic-programming { description "dynamic-programming indicates NETCONF ':function' capability. If the server advertises the :function capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled. When dynamic programming is enabled, the NETCONF server can provide interactive consoles to the client and can execute sets of functions, and can perform variable assignment for that session. When this feature is enabled and advertised, NETCONF should also provide the main language it supports as a hint for naming variables, equations and functions. For example, if NETCONF is primarily used to interface a MATLAB simulation, then :function:matlab should be advertised for the session. The name of the programming language given as hint should match one of the language identities provided by this YANG model. If no programming language is given as a hint, or if the client cannot resolve the language naming conventions, then naming conventions should use the instance-identifier type instead. A NETCONF session must not be dropped because the client and the server cannot agree on a common programming language."; reference "RFC7952 Defining and Using Metadata with YANG."; } feature dynamic-assignment { description "A NETCONF server capable of dynamic assignment allows a user access to any physical or mathematical variable by providing an abstract name, and can assign values to these abstract names."; } md:annotation name { type variable-name; description "This annotation allows assignment to a variable on the NETCONF server. The name must follow the naming convention (see variableName description). An assignment is made by defining name as an attribute of the encasing YANG node: leaf atmospheric-pressure { type si-unit:pressure; description 'This is how I represent the pressure in my model'; }. Assignments can be made with the following XML RPC: 1.01325e5 is equivalent to stating that a = 101,325 Pa. An message of type bad-attribute should be returned by the NETCONF server if: 1. Assignment is performed on a read only attribute (config false). 2. Assignment is performed on a conflicting operation. For example, assigning a value to a leaf where the operation on the container is 'delete'. If the assignment is implicit and no operation can be resolved, then the variable should be created."; } //============================================================================================= // // LIST OF PROGRAMMING LANGUAGES THAT COULD BE MATCHED TO OUR EXPERIMENTAL PACKAGE // //============================================================================================= identity language { description "Base identity from which all languages are derived."; } identity programming { description "Base identity specifying that the primary function of the language is for programming a device. If you use a language that was primarily for programming, but is now also considered 'universal,' such as Python numpy for example, do not use this base identity."; } identity math { description "Base identity specifying that the primary function of the language is for solving mathematical problems. If you use a language that is primarily for programming, but is now also considered 'universal,' such as Python numpy for example, do not use this base identity."; } identity matlab { base language; base math; description "Equation and variable names are written in native MATLAB format."; } identity mathematica { base language; base math; description "Equation and variable names are written in native Mathematica format."; } identity maple { base language; base math; description "Equation and variable names are written in native Maple format."; } identity octave { base language; base math; description "Equation and variable names are written in native Octave format."; } identity fortran { base language; base programming; description "Equation and variable names are written in native Fortran format."; } identity c { base language; base programming; description "Equation and variable names are written in native C or C++ format."; } identity python { base language; base programming; description "Equation and variable names are written in native Python format."; } identity numpy { base language; description "Equation and variable names are written in Python numpy format."; } //============================================================================================= // // PROGRAMMING CONCEPTS - VARIABLE NAME, FUNCTION DEFINITION // //============================================================================================= typedef variable-name { type union { type string { pattern '[A-Za-z._:][A-Za-z0-9._:]*'; } type instance-identifier; } description "A generic representation of a variable name. This type validates that the string identifying a variable is correct from the perspective of many languages. The implementation is expected having a smart lookup table. For example, we know that python can retrieve any attribute of a target instance or module by calling the getattr() function, and providing it the string name of this attribute. The format of the variable representation is outside the scope of this YANG model, and can be language dependent. XML XPath representation can be used if the NETCONF server has the XPath capability to resolve the variable name. If the implementation is coded in Python, a path with dots can be used to represent the target instance. For example 'foo.bar' would refer to attribute 'bar' in instance or module 'foo'. The type restriction of this name is believed to encompass as many language conventions as possible and must not override the string pattern of a number. Consequently, a valid name must: 1. Start with an alphabetical character, a dot, a colon, or an underscore 2. Is followed by any number of alphanumerical character, dots, colons and underscores 3. Prohibits dashes and spaces This is the XML naming convention, but this restriction allows the name to start with 'xml'. For example 'xml12' is a valid variable name (but it is not a valid xml tag). When the naming convention cannot be one of the popular languages, then this type automatically falls back to an instance-identifier, and the name should correspond to an instance in the data tree, otherwise the NETCONF server will raise an message."; } typedef number { type string { pattern '[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?(\s*[-+]\s*[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?[ij])?'; } description "A generic representation of a number. This type does not make assumptions regarding precision (simple, double etc., decimal32, 64) on the target computer. The number format is a string, so the implementation is expected to have parsing options to convert this value into an appropriate format on the system. For example, we know that Python is flexible enough to convert such a string into a float number. Examples of numbers that can be represented with this type: -1, 2, 0, +4.5e4, -.5e4, -1.2e-5, 0.34, -5.6e-4 - 16e3j We want to use this generic representation of a number to express any physical body without the need for specifying number limit representations (such as fraction-digit in decimal64 types). This way we can reuse a 'mass' to express the 'mass of Sun' or a 'mass of a proton' by keeping the same fundamental unit. NOTE: For Python users, spaces are allowed in this pattern to make a clear distinction between the real and the imaginary parts. complex() does not accept -5.6e-4 - 16e3j as valid format, but prefers -5.6e-4-16e3j. Spaces need to be replaced."; } typedef variable { type union { type number; type variable-name; } description "A variable is a mathematical or physical entity that can be referred as either a number for constants, or a name for variables. This union type helps assign or get values based on numbers or abstract names. Namespace design needs special care as name conflict mitigation is outside the scope of this YANG model. For example, namespace conflict can be solved by using dots or underscores (see YANG 1.1 instance-reference for XPath resolution). NOTE: name is an alias, and is not necessarily connected to any variable name upon implementation. The NETCONF server should store a mapping between variable names and the corresponding attributes on the implementation. This is also outside the scope of this YANG model. The NETCONF server should return an with an error of type 'bad-element' if the variable name cannot be retrieved."; } grouping function { container function { choice name-type { leaf name { type string; description "The function name, if it is a builtin or a well-known function such as sum, add, divide, langevin, etc."; } leaf id { type string; description "An identifier so that the NETCONF server knows what function to call, if the user has enough privileges to call this function. For example, os.path.isfile in Python."; } description "name-type gives the choice to name a function with a generic name or with a path on a target machine."; } leaf-list arg { type variable; ordered-by user; description "A list of positional arguments where order is important."; } description "A function is identified by its name and a variable list of positional arguments. For example, 1 + 2 can be translated into sum(1, 2), and then becomes an XML RPC of the following format: sum 1 2 Order is important because in some mathematical spaces 1 + 2 != 2 + 1."; } description "A reusable function definition."; } //============================================================================================= // // RPC TO CALL A TARGET FUNCTION ON THE CURRENT SESSION // //============================================================================================= rpc call { description "Calls a target function for this session and gets the returned value."; input { uses function; } output { anyxml result { description "The return value of the function."; } } } }