module ieee1906-dot1-math {

    yang-version 1.1;

    namespace
      "urn:ieee:std:1906.1:yang:ieee1906-dot1-math";

    prefix ieee1906-math;

    import ieee1906-dot1-function {
      prefix function;
    }

    organization
      "IEEE Std 1906.1-2015 - Recommended Practice for Nanoscale and
Molecular Communication Framework Working Group";

    contact
      "Stephen F. Bush <bushsf@research.ge.com>
Guillaume Mantelet <gmantelet@voltigeurnetworks.com>";

    description
      "This module aims to represent YANG data as dynamic, allowing the user to provide
data as variable abstract names. Assignment can be performed, and data
representation can be made by using variable names instead of values if they are
not (yet) resolved.

For example, a mass flow rate can be defined either in its mdot notation when it
can be resolved, or as a product between a mass density and a volume flow rate.
The two attributes can be provided by their variable names if the NETCONF client
does not resolve their values. The NETCONF server can return the corresponding
mdot value, or if applicable, can return the two attribute values.

This module defines also various mathematical concepts and objects such as
vectors, tensors, equations as long as consensus exists. Modeling the equation
itself is outside the scope of this YANG model. This YANG model scope is to
define the inputs and outputs of these equations.

The following table summarizes the mathematical concepts defined in this YANG
model.

+-------------+-----------+------------------------------------------------------+
| name        | type      | description                                          |
+-------------+-----------+------------------------------------------------------+
| equation    | extension | List of expressions, optional symbol units, and name |
| expression  | extension | List of unknowns and variables                       |
| name        | extension | Giving a container a name                            |
+-------------+-----------+------------------------------------------------------+
| nabla       | grouping  | Differential operator in cartesian units             |
| scalar      | typedef   | Unitless and dimensionless value                     |
| surface     | grouping  |                                                      |
| symbol      | extension | A human friendly hint in equations                   |
| value       | extension | A variable giving the equation a result or a name    |
| vector      | grouping  |                                                      |
| vector-area | grouping  |                                                      |
+-------------+-----------+------------------------------------------------------+
";

    revision "2020-12-07" {
      description "Initial version.";
      reference
        "'IEEE Recommended Practice for Nanoscale and Molecular Communication Framework,'
         in IEEE Std 1906.1-2015, pp.1-64, Jan. 11 2016
         doi: 10.1109/IEEESTD.2016.7378262";

    }


    extension equation {
      argument "equation-name" {
        yin-element false;
      }
      description
        "An equation is a list of expressions.

The equation is considered well known and easy to obtain a consensus to within
the scientific community. It is outside the scope of this YANG model to describe
what the equation does. Instead, this YANG model refers to well-known or
consensual equations.

For example, the mass flow rate equation is well known and has the following
accepted expressions:
mdot = rho . Vdot = rho . V . A = jm . A

Note that this naming uses symbols. Symbols are also defined and are only hints
for a human user. Convention should use the name attached to the symbol to get a
meaningful notion of what is expressed.

An equation can be named for functional programming purposes. An equation may
have a value. In the example of the mass flow rate equation, mdot is the value.
The value is a function:variable.";
    }

    extension expression {
      description
        "An expression is part of an equation. Two expressions in an equation are
equivalent. An expression is a list of unknown or variables linked by
operations.

The expression is considered well known and easy to obtain a consensus to within
the scientific community. It is outside of the scope of this YANG model to
describe the relationship between the unknown.

Instead, the expression provides a list of unknowns or variables.";
    }

    extension symbol {
      argument "symbol-name" {
        yin-element false;
      }
      description
        "To provide a known name that represents this type. Adds nothing to a NETCONF
server.";
    }

    extension value {
      description
        "The value part of the equation which MUST be of type function:variable.

The result of the equation. It can be used to directly configure the server.
Or the value is returned by the server as a result of a call, a simulation, a
mathematical process.

This is a variable. A numerical value can be provided. Or, if it is unknown,
or in case of functional programming, the target variable name can be used
instead.";
    }

    extension name {
      argument "name" {
        yin-element false;
      }
      description
        "An optional name to use an equation as an unknown for functional programming.
The name MUST be of type function:variableName.";
    }

    typedef scalar {
      type function:variable;
      description
        "A scalar is a dimensionless and unitless value. Please refer to the si-unit
system if the scalar has a meaning. This is a variable, but by defining it as a
scalar, it is explicitly not a vector coordinate.";
    }

    grouping surface {
      description
        "A reusable container modelling a surface.";
      container surface {
        ieee1906-math:symbol "A";
        ieee1906-math:name "name";
        description "A surface.";
        leaf-list scalar {
          type scalar;
          description
            "A scalar representing this surface in the considered space.";
        }
      }  // container surface
    }  // grouping surface

    grouping vector {
      ieee1906-math:symbol "v";
      ieee1906-math:name "name";
      description "A reusable vector.";
      choice vector-type {
        description
          "A vector can be described in three different types of coordinates,
euclidian, polar and spherical.";
        container vector {
          description
            "A generic container representing a vector in any base.
Ordering is very important, and providing at least one element is
mandatory.

Physicists will often refer to a vector with three coordinates. Convention
on the dimensions, unless otherwise specified, is x, y, z.";
          leaf-list coordinate {
            type function:variable;
            ordered-by user;
            description
              "A coordinate of this vector. It can be named.";
          }
        }  // container vector
        container polar-vector {
          description
            "A generic container representing a vector in polar coordinates.";
          leaf radius {
            type function:variable;
            description
              "Or magnitude, it is the distance from a reference point. It can be named.";
          }

          leaf polar-angle {
            type function:variable;
            description
              "The angle of this vector from a reference vector. It can be named.";
          }
        }  // container polar-vector
        container spherical-vector {
          description
            "A generic container representing a vector in spherical coordinates.";
          leaf radius {
            type function:variable;
            description
              "Or magnitude, it is the distance from a reference point. It can be named.";
          }

          leaf polar-angle {
            type function:variable;
            description
              "The angle of this vector from a reference vector. It can be named.";
          }

          leaf azimuthal-angle {
            type function:variable;
            description
              "The angle of this vector from a reference vector. It can be named.";
          }
        }  // container spherical-vector
      }  // choice vector-type
    }  // grouping vector

    grouping vector-area {
      ieee1906-math:equation "vectorArea" {
        ieee1906-math:symbol "S";
        ieee1906-math:value;
        ieee1906-math:expression {
          uses "vector";
          uses "surface";
          description "A vector area is a unit normal scaled by its surface.";
        }
        description "A vector area is the product of the unit norm (a vector) by a surface area. It
can be named.";
      }
      description
        "Making this container reusable.";
    }  // grouping vector-area

    grouping nabla {
      description
        "The result of the differential operator SIGMA(d/di) at a given position.";
      container nabla {
        description
          "A generic container representing the Cartesian coordinate for 
this nabla. Ordering is very important, and providing at least 
one element is mandatory.

Physicists will often refer to an operator with three coordinates. 
Convention on the dimensions, unless otherwise specified, is x, y, z.";
        leaf-list coordinate {
          type function:variable;
          ordered-by user;
          description
            "Cartesian coordinates for this nabla operator. It can be named.";
        }
      }  // container nabla
    }  // grouping nabla

    typedef percent {
      type union {
        type string {
          pattern
            '[+\-]?([0-9][0-9]?(\.?[0-9]+([eE][-+]?[0-9]+)?)|100)%?';
        }
        type function:variable-name;
      }
      description
        "A 'classical' percentage is a number x such as 0 <= x <= 100";
    }

    typedef proper-fraction {
      type union {
        type string {
          pattern
            '[+\-]?(0(\.?[0-9]+([eE][-+]?[0-9]+)?)|1)';
        }
        type function:variable-name;
      }
      description
        "A fraction that is less than or equals 1";
    }

    typedef probability {
      type union {
        type string {
          pattern
            '(0(\.?[0-9]+([eE][-+]?[0-9]+)?)|1)';
        }
        type function:variable-name;
      }
      description
        "A 'classical' probability is a number x such as 0 <= x <= 1. Other types of
probabilities (e.g. exotic and negative probabilities) are not included in
this definition.";
    }

    grouping probability-density-function {
      description "A reusable pdf.";
      leaf-list probability-density-function {
        type probability;
        units "probability";
        description
          "A list of probabilities forming a probability density function.";
      }
    }  // grouping probability-density-function
  }  // module ieee1906-dot1-math