diff --git a/_sources/changelog.rst b/_sources/changelog.rst index 3aa9219fe..db2707a84 100644 --- a/_sources/changelog.rst +++ b/_sources/changelog.rst @@ -7,6 +7,9 @@ Changelog New ~~~ +- It is now possible to index into the tensors of derivatives + using indices vectors in sparse format + (`#389 `__). - Add support for Lagrangian and Hamiltonian mechanics (`#381 `__, `#379 `__). diff --git a/_sources/expression.rst b/_sources/expression.rst index f3e7e5161..28f5cb7ca 100644 --- a/_sources/expression.rst +++ b/_sources/expression.rst @@ -10,8 +10,109 @@ The :cpp:class:`expression` class .. cpp:class:: expression + Class to represent symbolic expressions. + + This is the main class used to represent mathematical expressions in heyoka. + It is a union of several types: + + - :ref:`symbolic variables `, + - :ref:`numerical constants `, + - :ref:`runtime parameters `, + - :ref:`n-ary functions `. + + Because expressions are essentially `trees `__, + we refer to these types as the *node types* of an expression. + + Expressions can be created in a variety of ways. After creation, expressions + can be combined via :ref:`arithmetic operators ` and :ref:`mathematical functions ` + to form new expressions of arbitrary complexity. + + Expressions which consist of a single :ref:`variable ` or a single + :ref:`constant `/:ref:`parameter ` are referred to as + *elementary* expressions. + + Expressions provide an immutable API: after creation, an expression cannot be changed in-place + (except via assignment or swapping). + .. cpp:type:: value_type = std::variant + The union of node types. + + .. cpp:function:: expression() noexcept + + Default constructor. + + This constructor initialises the expression to a double-precision :ref:`number ` with a value of zero. + + .. cpp:function:: explicit expression(float x) noexcept + + .. cpp:function:: explicit expression(double x) noexcept + + .. cpp:function:: explicit expression(long double x) noexcept + + .. cpp:function:: explicit expression(mppp::real128 x) noexcept + + .. cpp:function:: explicit expression(mppp::real x) + + Constructors from floating-point objects. + + These constructors initialise the expression to a floating-point :ref:`number ` with the input value *x*. + Expressions can be constructed from objects of any floating-point type supported by :ref:`number `. + + :param x: the construction argument. + + :exception: any exception raised by the copy constructor of :cpp:class:`mppp::real`. + + .. cpp:function:: explicit expression(std::string s) + + Constructor from variable name. + + This constructor initialises the expression to a :ref:`variable ` constructed from the + input string *s*. + + :param s: the variable name. + + :exception: any exception thrown by the copy constructor of ``std::string``. + + .. cpp:function:: explicit expression(number x) + + .. cpp:function:: explicit expression(variable x) + + .. cpp:function:: explicit expression(func x) noexcept + + .. cpp:function:: explicit expression(param x) noexcept + + Constructors from objects of the node types. + + These constructors will initialise the internal union with the input argument *x*. + + :param x: the construction argument. + + :exception: any exception raised by the copy constructor of :cpp:class:`number` or :cpp:class:`variable`. + + .. cpp:function:: expression(const expression &) + + .. cpp:function:: expression(expression &&) noexcept + + .. cpp:function:: expression &operator=(const expression &) + + .. cpp:function:: expression &operator=(expression &&) noexcept + + .. cpp:function:: ~expression() + + Expressions are copy/move constructible/assignable and destructible. + + Note that because :cpp:class:`func` employs reference semantics, copying/assigning + a non-elementary expression is a constant-time operation. + + :exception: any exception thrown by the copy constructor/copy assignment operators of the active node types. + + .. cpp:function:: [[nodiscard]] const value_type &value() const noexcept + + Const accessor to the internal union. + + :return: a const reference to the internal :cpp:type:`value_type` instance. + Functions --------- @@ -41,6 +142,11 @@ Functions auto x = make_vars("x"); auto [y, z] = make_vars("y", "z"); +.. _api_ex_arith_ops: + +Arithmetic operators +-------------------- + User-defined literals --------------------- diff --git a/changelog.html b/changelog.html index 7fe36cf0d..6d0a20fe8 100644 --- a/changelog.html +++ b/changelog.html @@ -573,6 +573,9 @@

4.0.0 (unreleased)

New#

+
  • Arithmetic operators
  • User-defined literals
  • +
  • Arithmetic operators
  • User-defined literals