LEM Documentation

A Toolbox for Large Expression Management

Authors
Affiliation

Davide Stocco

University of Trento (Italy)

Matteo Larcher

University of Trento (Italy)

Enrico Bertolazzi

University of Trento (Italy)

This is the documentation for the LEM package. This is a module for Large Expressions Management in Maple. The module is very similar to the ‘LargeExpression’ module provided by Maple. The main difference is that the ‘LEM’ module has some built-in functions to collect, display, list and substitute the veiled expressions in a more user-friendly and object-oriented fashion.

The following code is hopefully an improved version of the LULEM package described in the following PhD thesis:

We would like to thank Jacques Carette for providing the original code that have inspired this module.

1 Installation

Download the package from the GitHub repository, release the zip file, and follow the instructions below. Optionally, you can clone the repository using the following command:

git clone https://github.com/StoccoDavide/LEM.git

1.1 Maple

To install the module you must have first installed Maple (2020 or later). Then open the PackAndGo.mw file and use the !!! button to execute the entire worksheet.

Then test the module in a Maple worksheet or document by executing LEM:-Info() or Describe(LEM). Alternatively, you can use one of the test files provided in the maple/tests folder. If the module is loaded without errors, it is done!

🚧 Attention! 🚧

Both LEM and LAST packages are written to work in an object-oriented programming style. Please note that Maple object-oriented programming features have slightly changed in 2021, which online documentation states:

As of Maple 2021, if the method has a formal parameter named _self, references to its object’s local or exported variables may be written without prefixing them. That is, _self:-variable may be written as just variable. Maple will add the self:- prefix internally when the method is simplified.

As of Maple 2021, a message-passing form of method call can be used, which will automatically pass the object as an argument if the method has a formal parameter named _self.

Another way to invoke a method, similar to that used in other object-oriented languages, was introduced in Maple 2021. In this form, the object name is qualified by the method name, object_name:-method_name(argument) just as it can be in the function mechanism described above. However, the object can be omitted from the argument sequence.

For further information please refer to the following link.

2 License

BSD 3-Clause License

Copyright (c) 2023 Current version: Davide Stocco, Matteo Larcher and Enrico Bertolazzi.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

3 Usage

In case you have no time to read through all the APIs and realize how the toolbox should or should not work, refer to the files prensent in maple/tests folder. This contains usage examples with increasing complexity and detail.

4 Maple API

4.1 Module Utilities

Info

Print module information.

  • Inputs: None.
  • Optional inputs: None.
  • Returns: NULL.

Proto: Info()

ModuleLoad

Module load procedure.

  • Inputs: None.
  • Optional inputs: None.
  • Returns: NULL.

Proto: ModuleLoad()

ModuleUnload

Module unload procedure.

  • Inputs: None.
  • Optional inputs: None.
  • Returns: NULL.

Proto: ModuleLoad()

ModuleCopy

Copy the object proto.

  • Inputs: _self::LEM, proto::LEM.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-ModuleCopy(_self, proto)

EnableVerboseMode

Enable the verbosity of the module.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-EnableVerboseMode(_self)

DisableVerboseMode

Disable the verbosity of the module.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-DisableVerboseMode(_self)

SetVerboseMode

Set the verbosity of the module to mode.

  • Inputs: _self::LEM, mode::boolean.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-SetVerboseMode(_self, mode)

EnableWarningMode

Enable the warning mode of the module.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-EnableWarningMode(_self)

DisableWarningMode

Disable the warning mode of the module.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-DisableWarningMode(_self)

SetWarningMode

Set the warning mode of the module to mode.

  • Inputs: _self::LEM, mode::boolean.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-SetWarningMode(_self, mode)

4.2 Module Interface

SetVeilingLabel

Set the veiling label to label.

  • Inputs: _self::LEM, label::{string, symbol}.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-SetVeilingLabel(_self, label)

SetVeilingDeps

Set the veiling dependencies to deps.

  • Inputs: _self::LEM, deps::list.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-SetVeilingDeps(_self, deps)

GetVeilingDeps

Return the veiling dependency.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: list.

Proto: _self:-GetVeilingDeps(_self)

ClearVeilingDeps

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-ClearVeilingDeps(_self)

GetVeilingLabel

Return the veiling label.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: symbol.

Proto: _self:-GetVeilingLabel(_self)

EnableSignatureMode

Enable the expression signature calculation.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-EnableSignatureMode(_self)

DisableSignatureMode

Disable the expression signature calculation.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-DisableSignatureMode(_self)

SetSignatureMode

Set the expression signature calculation of the module to mode.

  • Inputs: _self::LEM, mode::boolean.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-SetSignatureMode(_self, mode)

Veil

Check if the veiling strategy is verified, if true veil the expression x and return a label to it.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: depend::list := [], force::boolean := false.
  • Returns: anything.

Proto: _self:-Veil(_self, x, depend = [], force = false)

VeilSig

Veil the expression x and return a label to it.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-VeilSig(_self, x)

VeilImap

Return the permutation map of the veiling labels.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-VeilImap(_self)

SigImap

Return the permutation map of the signature labels.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-SigImap(_self)

ExpressionCost

Compute the cost of the expression x.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: dependencies::boolean := true.
  • Returns: integer.

Proto: _self:-ExpressionCost(_self, x, dependencies = true)

TreeNodes

Given the expression x, return the directed acyclic graph’s nodes (optimized version).

  • Inputs: x::anything.
  • Optional inputs: r::boolean := true.
  • Returns: anything.

Proto: TreeNodes(x, r = true)

TreeStructure

Given the expression x, return the directed acyclic graph’s edges, nodes, and leafs.

  • Inputs: x::anything.
  • Optional inputs: None.
  • Returns: anything.

Proto: TreeStructure(x)

VeilingStrategy

Evaluate the veiling strategy for the expression x.

  • Inputs: _self::LEM, x::algebraic.
  • Optional inputs: None.
  • Returns: boolean.

Proto: _self:-VeilingStrategy(_self, x)

SetExprMaxCost

Set the maximum expression cost maxcost for veiling.

  • Inputs: _self::LEM, maxcost::nonnegint.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-SetExprMaxCost(_self, maxcost)

GetExprMaxCost

Get the maximum expression cost for veiling.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: nonnegint.

Proto: _self:-GetExprMaxCost(_self)

Unveil

Unveil the expression x with the veiled variables.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-Unveil(_self, x)

UnveilSig

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-UnveilSig(_self, x)

UnveilImap

Unveil the expression x with the veiling labels permutation map.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-UnveilImap(_self, x)

SigImap

Unveil the expression x with signature values permutation map.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-SigImap(_self, x)

VeilDepsList

Return a list of the veiling labels dependency substitution.

  • Inputs: _self::LEM.
  • Optional inputs: reverse::boolean := false.
  • Returns: list.

Proto: _self:-VeilDepsList(_self, reverse = false)

VeilList

Return a list of the veiling labels.

  • Inputs: _self::LEM.
  • Optional inputs: dependency::boolean := false, reverse::boolean := false.
  • Returns: list.

Proto: _self:-VeilList(_self, dependency = false, reverse = false)

VeilList

Return a list of the veiling labels.

  • Inputs: _self::LEM.
  • Optional inputs: dependency::boolean := false, reverse::boolean := false.
  • Returns: list.

Proto: _self:-VeilList(_self, dependency = false, reverse = false)

SigList

Return a list of the signature labels.

  • Inputs: _self::LEM.
  • Optional inputs: reverse::boolean := false.
  • Returns: list.

Proto: _self:-SigList(_self, reverse = false)

VeilUnorderedList

Return the unordered veiling list.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: list.

Proto: _self:-VeilUnorderedList(_self)

SigUnorderedList

Return the unordered signature list.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: list.

Proto: _self:-SigUnorderedList(_self)

VeilTableSize

Return the size of the internal veiling table.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: nonnegint.

Proto: _self:-VeilTableSize(_self)

SigTableSize

Return the size of the internal signature table.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: nonnegint.

Proto: _self:-SigTableSize(_self)

VeilTableImap

Return the veiling list and the permutation that sorts it.

  • Inputs: _self::LEM.
  • Optional inputs: reverse::boolean := false.
  • Returns: {list(anything = anything), []}.

Proto: _self:-VeilTableImap(_self, reverse = false)

SigTableImap

Return the signature list and the permutation that sorts it.

  • Inputs: _self::LEM.
  • Optional inputs: reverse::boolean := false.
  • Returns: {list(anything = anything), []}.

Proto: _self:-SigTableImap(_self, reverse = false)

TablesAppend

Append the veiled expression x to the veiling table.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: None.
  • Returns: indexed.

Proto: _self:-TablesAppend(_self, x)

SubsVeil

Substitute the reversed veiling variables of the internal veiling table in the expression x. If dependency flag dependency is set to true, the veiling variables are substituted with their dependencies.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: dependency::boolean := false, reverse::boolean := true.
  • Returns: anything.

Proto: _self:-SubsVeil(_self, x, dependency = false, reverse = true)

SubsSig

Substitute the reversed signature values of the internal signature table in the expression x.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: None.
  • Returns: anything.

Proto: _self:-SubsSig(_self, x)

ForgetVeil

Clear the internal veiling and signature tables.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-ForgetVeil(_self)

ForgetSig

Clear the internal veiling signature tables.

  • Inputs: _self::LEM.
  • Optional inputs: None.
  • Returns: NULL.

Proto: _self:-ForgetSig(_self)

Sig

Compute the signature of the expression x modulo p (the default is the internal signature value). Verbosity can be enabled with the flag verbose.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: verbose::boolean := false.
  • Returns: anything.

Proto: _self:-Sig(_self, x, verbose = false)

Signature

Compute the signature of the expression x modulo p (the default is the internal signature value) also by using the internal signature table of the veiled expressions. Verbosity can be enabled with the flag verbose.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: verbose::boolean := false.
  • Returns: anything.

Proto: _self:-Signature(_self, x, verbose = false)

IsZero

Check if the expression x is zero by evaluating the signature of the expression and substituting the signature values already computed. Verbosity can be enabled with the flag verbose.

  • Inputs: _self::LEM, x::anything.
  • Optional inputs: verbose::boolean := false.
  • Returns: boolean.

Proto: _self:-IsZero(_self, x, verbose = false)