Difference between revisions of "ApCoCoA-1:MatlabToolbox"

From ApCoCoAWiki
(New page: = Introduction = This article presents the current implementation of the Matlab Toolbox. The toolbox provides functions to run ApCoCoA functions inside Matlab. All current available functi...)
 
 
(15 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
This article presents the current implementation of the Matlab Toolbox. The toolbox provides functions to run ApCoCoA functions inside Matlab. All current available functions will be presented here. The general approach is explained in the following section: MatlabToolbox Interface.
+
The MatlabToolbox is a collection of .m and .mex files to use the functions provided by the ApCoCoALib. Classes representing rings, polynomials, ideals and modules are added to provide an intuitive approach to the algebraic nature of the functions.
  
= MatlabToolbox_Interface =
+
To overcome technical difficulties the interaction with the ApCoCoALib is done via a dll. For more technical details how this dll is programmed have a look at the [http://www.apcocoa.org/wiki/ApCoCoA:MatlabInterface MatlabToolbox Interface].
As the ApCoCoALib is written in c++ an additional dll is created to provide a way of communication between mex files and the ApCoCoALib. A detailed description of this approach and current available ApCoCoA functions are described here: [[ApCoCoA:MatlabToolbox_Interface|MatlabToolbox_Interface]]
 
  
= Functions =
+
For Windows users we offer a setup program which will install the MatlabToolbox (called ApCoCoA-Matlab-Interface) with a precompiled version of the CoCoALib (0.99.30) and ApCoCoALib 1.1. See the download section for the download link.
Available functions are:
+
 
* PreProcessing
+
If you want to compile the MatlabToolbox on your own (e.g. with a newer CoCoALib or ApCoCoALib version) we provide a detailed description on how to do so on Windows with MSVC. Read the howto page for a description of the compilation process: [http://www.apcocoa.org/wiki/HowTo:Compile_MatlabToolbox_on_Windows HowTo: Compile MatlabToolbox on Windows]
 +
 
 +
Note: From a perspective of an ApCoCoA User this toolbox provides an interface to communicate with Matlab - thus the toolbox is called in this Wiki ''MatlabToolbox''. Yet from the perspective of a Matlab user the toolbox provides an interface to communicate with the ApCoCoALib - thus the compiled library is called ''ApCoCoAToolbox.dll''.
 +
 
 +
= MatlabToolbox structure =
 +
The toolbox is based on classes to handle multivariate polynomials. The concept is based on a ring representing class called CoCoARing. Then a multivariate polynomial is build with coefficients defined over a CoCoARing. The polynomial is an element of the CoCoAPoly class.
 +
 
 +
Multiple CoCoAPoly's can be combined in an array. In many cases a list of polynomials (a 1xN array) is interpreted as the set of generators of an ideal. To represent this view and provide common operations on ideals the class CoCoAIdeal is introduced.
 +
 
 +
A MxN array of CoCoAPoly's could then be interpreted as a set of generators for a module and the class CoCoAModule is introduced to provide common module operations.
 +
 
 +
[[Image:ToolboxStructure.png|thumb|right|350px|Figure 1: Class structure]]
 +
 
 +
Note: Due to technical limitations the current implementation assumes that all polynomials are defined over the ring Q[x1,...xn]. General ring support in the CoCoAPoly class will be added in a later stage.
 +
 
 +
The structure of the MatlabToolbox is depicted in figure 1.
 +
==Class descriptions==
 +
Detailed descriptions for each class and its methods are given at the following links:
 +
* [[ApCoCoA:MatlabCoCoARing|CoCoARing]]
 +
* [[ApCoCoA:MatlabCoCoAPoly|CoCoAPoly]]
 +
* [[ApCoCoA:MatlabCoCoAIdeal|CoCoAIdeal]]
 +
* [[ApCoCoA:MatlabCoCoAModule|CoCoAModule]]
 +
 
 +
=Available functions=
 +
The interface provides mex functions to call the ApCoCoALib functions. These functions are located in the subfolder ''MexFiles''.
 +
 
 +
But the mex files parameters for polynomial operations are based on double matrices representing the polynomials. This syntax is far away from an intuitive handling of polynomials. Thus wrapper functions have been written to provide automated conversion from CoCoAPoly's, CoCoAIdeal's or CoCoAModule's.
 +
 
 +
For example to compute the Groebner Basis of an ideal one can call the function ''GBasisIdeal_wrap(InputIdeal)'' which takes a CoCoAIdeal, computes the Groebner Basis and returns the result as a CoCoAPoly list. To store the Groebner Basis in the ideal the ideal method ''computeGBasis(InputIdeal)'' can be used. This functions also computes the Groebner Basis but adds the result to the ideals attribute GBasis.
 +
 
 +
The wrapper files are bundled in a subfolder called ''MatlabFiles''. The filename is indicating which type of input is needed. E.g. ''GBasisIdeal_wrap()'' takes a CoCoAIdeal and returns the Groebner Basis as a list of CoCoAPoly's.
 +
 
 +
The mex files and if available the corresponding wrapper files are individually described at the following links. In case that there are versions available for ideals and modules these functions are described on the same page. Note that some of the mex files are used to define methods for the described classes and that there is no corresponding wrapper file available.
 +
 
 +
For examples on how to use the mex and wrapper functions see the test file: [http://www.apcocoa.org/wiki/ApCoCoA:TestMexFiles Test Mex Files]
 +
 
 +
<table border="1">
 +
  <tr>
 +
    <td>'''ApCoCoALib'''</td>
 +
    <td></td>
 +
    <td>'''CoCoALib'''</td>
 +
    <td></td>
 +
    <td></td>
 +
    <td></td>
 +
    <td></td>
 +
  </tr>
 +
  <tr>
 +
    <td>Build-Info ApCoCoALib</td>
 +
    <td></td>
 +
    <td>Build-Info CoCoALib</td>
 +
    <td>[[CoCoA:GBasis|GBasis]]</td>
 +
    <td>PolyPower</td>
 +
    <td>PolyRingHom</td>
 +
    <td>[[CoCoA:Saturation|Saturation]]</td>
 +
  </tr>
 +
  <tr>
 +
    <td>[[ApCoCoA:Num.AVI|AVI]] and [[ApCoCoA:Num.ABM|ABM]]</td>
 +
    <td></td>
 +
    <td>CColon</td>
 +
    <td>[[CoCoA:Intersection|Intersection]]</td>
 +
    <td>PolyPlus</td>
 +
    <td>[[CoCoA:PreprocessPts5|PreProcess (Grid, Aggr, Subdiv)]]</td>
 +
    <td>SSaturation</td>
 +
  </tr>
 +
  <tr>
 +
    <td>[[ApCoCoA:BBasis|BorderBasisIdeal]]</td>
 +
    <td></td>
 +
    <td>[[CoCoA:Colon|Colon]]</td>
 +
    <td>[[CoCoA:IsIn|IsElemIdeal]]</td>
 +
    <td>PolyMinus</td>
 +
    <td>SATGBasis</td>
 +
    <td>[[CoCoA:Syz|SyzygyPolyList]]</td>
 +
  </tr>
 +
  <tr>
 +
    <td>[[ApCoCoA:FGLM|FGLM]]</td>
 +
    <td></td>
 +
    <td>[[CoCoA:Elim|EliminationIdeal]]</td>
 +
    <td>[[CoCoA:LT|LeadingTermIdeal]]</td>
 +
    <td>PolyMult</td>
 +
    <td>SATMixGBasis</td>
 +
    <td>[[CoCoA:Syz|SyzygyIdeal]]</td>
 +
  </tr>
 +
</table>
 +
 
 +
= Matlab Toolbox in Action =
 +
 
 +
[[Image:DemoToolboxGBEvaluation.png|thumb|right|350px|Figure 2: Demo of Matlab Toolbox]]
 +
 
 +
The screenshot (Figure 2) shows how one can create polynomials (CoCoAPoly-class) with the help of the simple string parser. The polynomials are used to construct an ideal (CoCoAIdeal-class) and the Groebner-Basis of the ideal is computed with the CoCoALib function GBasis.
 +
 
 +
The last basis element is then taken and evaluated over a set of points. The evaluation is plotted with the usual plot command.
  
 
= Download =
 
= Download =
The current version can be downloaded here. (add link)
+
The MatlabToolbox is available on Windows in form of a setup program in the current Version 1.03. The setup will install all needed Matlab files, the needed CoCoALib and ApCoCoALib as well as installing the pathes in Matlab to register the toolbox.
 +
 
 +
The installation of the pathes is done via a script which is copied in the 'work' directory of your Matlab installation. The script is called
 +
startup.m and is loaded upon start-up of Matlab. The precompiled DLL's are based on CoCoALib 0.99.30 and the ApCoCoA 1.1. The setup provides an uninstall program which will remove all files installed by the ApCoCoA-Matlab-Interface (the MatlabToolbox).
 +
 
 +
Note: Please Uninstall your current ApCoCoA-Matlab-Interface before installing a new version.
 +
The setup is provided as a zip-file at the following link: [http://www.apcocoa.org/~mmachnik/interface/Setup1-03.zip Download]
 +
 
 +
== History ==
 +
Note: Please Uninstall your current ApCoCoA-Matlab-Interface before installing a new version.
 +
*Version 1.03 (24.06.2009): Update to CoCoALib 0.99.30 and ApCoCoALib 1.1. Function ABM added.
 +
*Version 1.02 (31.01.2009): Update to CoCoALib 0.99.25 and ApCoCoALib as of 30.01.2009. Function to plot order ideals added.
 +
*Version 1.01 (21.11.2008): Initial online version.
 +
 
  
 
[[Category:MatlabToolbox]]
 
[[Category:MatlabToolbox]]

Latest revision as of 12:02, 13 September 2019

Introduction

The MatlabToolbox is a collection of .m and .mex files to use the functions provided by the ApCoCoALib. Classes representing rings, polynomials, ideals and modules are added to provide an intuitive approach to the algebraic nature of the functions.

To overcome technical difficulties the interaction with the ApCoCoALib is done via a dll. For more technical details how this dll is programmed have a look at the MatlabToolbox Interface.

For Windows users we offer a setup program which will install the MatlabToolbox (called ApCoCoA-Matlab-Interface) with a precompiled version of the CoCoALib (0.99.30) and ApCoCoALib 1.1. See the download section for the download link.

If you want to compile the MatlabToolbox on your own (e.g. with a newer CoCoALib or ApCoCoALib version) we provide a detailed description on how to do so on Windows with MSVC. Read the howto page for a description of the compilation process: HowTo: Compile MatlabToolbox on Windows

Note: From a perspective of an ApCoCoA User this toolbox provides an interface to communicate with Matlab - thus the toolbox is called in this Wiki MatlabToolbox. Yet from the perspective of a Matlab user the toolbox provides an interface to communicate with the ApCoCoALib - thus the compiled library is called ApCoCoAToolbox.dll.

MatlabToolbox structure

The toolbox is based on classes to handle multivariate polynomials. The concept is based on a ring representing class called CoCoARing. Then a multivariate polynomial is build with coefficients defined over a CoCoARing. The polynomial is an element of the CoCoAPoly class.

Multiple CoCoAPoly's can be combined in an array. In many cases a list of polynomials (a 1xN array) is interpreted as the set of generators of an ideal. To represent this view and provide common operations on ideals the class CoCoAIdeal is introduced.

A MxN array of CoCoAPoly's could then be interpreted as a set of generators for a module and the class CoCoAModule is introduced to provide common module operations.

Figure 1: Class structure

Note: Due to technical limitations the current implementation assumes that all polynomials are defined over the ring Q[x1,...xn]. General ring support in the CoCoAPoly class will be added in a later stage.

The structure of the MatlabToolbox is depicted in figure 1.

Class descriptions

Detailed descriptions for each class and its methods are given at the following links:

Available functions

The interface provides mex functions to call the ApCoCoALib functions. These functions are located in the subfolder MexFiles.

But the mex files parameters for polynomial operations are based on double matrices representing the polynomials. This syntax is far away from an intuitive handling of polynomials. Thus wrapper functions have been written to provide automated conversion from CoCoAPoly's, CoCoAIdeal's or CoCoAModule's.

For example to compute the Groebner Basis of an ideal one can call the function GBasisIdeal_wrap(InputIdeal) which takes a CoCoAIdeal, computes the Groebner Basis and returns the result as a CoCoAPoly list. To store the Groebner Basis in the ideal the ideal method computeGBasis(InputIdeal) can be used. This functions also computes the Groebner Basis but adds the result to the ideals attribute GBasis.

The wrapper files are bundled in a subfolder called MatlabFiles. The filename is indicating which type of input is needed. E.g. GBasisIdeal_wrap() takes a CoCoAIdeal and returns the Groebner Basis as a list of CoCoAPoly's.

The mex files and if available the corresponding wrapper files are individually described at the following links. In case that there are versions available for ideals and modules these functions are described on the same page. Note that some of the mex files are used to define methods for the described classes and that there is no corresponding wrapper file available.

For examples on how to use the mex and wrapper functions see the test file: Test Mex Files

ApCoCoALib CoCoALib
Build-Info ApCoCoALib Build-Info CoCoALib GBasis PolyPower PolyRingHom Saturation
AVI and ABM CColon Intersection PolyPlus PreProcess (Grid, Aggr, Subdiv) SSaturation
BorderBasisIdeal Colon IsElemIdeal PolyMinus SATGBasis SyzygyPolyList
FGLM EliminationIdeal LeadingTermIdeal PolyMult SATMixGBasis SyzygyIdeal

Matlab Toolbox in Action

Figure 2: Demo of Matlab Toolbox

The screenshot (Figure 2) shows how one can create polynomials (CoCoAPoly-class) with the help of the simple string parser. The polynomials are used to construct an ideal (CoCoAIdeal-class) and the Groebner-Basis of the ideal is computed with the CoCoALib function GBasis.

The last basis element is then taken and evaluated over a set of points. The evaluation is plotted with the usual plot command.

Download

The MatlabToolbox is available on Windows in form of a setup program in the current Version 1.03. The setup will install all needed Matlab files, the needed CoCoALib and ApCoCoALib as well as installing the pathes in Matlab to register the toolbox.

The installation of the pathes is done via a script which is copied in the 'work' directory of your Matlab installation. The script is called startup.m and is loaded upon start-up of Matlab. The precompiled DLL's are based on CoCoALib 0.99.30 and the ApCoCoA 1.1. The setup provides an uninstall program which will remove all files installed by the ApCoCoA-Matlab-Interface (the MatlabToolbox).

Note: Please Uninstall your current ApCoCoA-Matlab-Interface before installing a new version. The setup is provided as a zip-file at the following link: Download

History

Note: Please Uninstall your current ApCoCoA-Matlab-Interface before installing a new version.

  • Version 1.03 (24.06.2009): Update to CoCoALib 0.99.30 and ApCoCoALib 1.1. Function ABM added.
  • Version 1.02 (31.01.2009): Update to CoCoALib 0.99.25 and ApCoCoALib as of 30.01.2009. Function to plot order ideals added.
  • Version 1.01 (21.11.2008): Initial online version.