CoCoALib-0.9905 date: 23 May 2007


CoCoA::ModuleBase Class Reference

#include <module.H>

Inheritance diagram for CoCoA::ModuleBase:

Inheritance graph
[legend]
List of all members.

Public Types

typedef ModuleRawPtr RawPtr
typedef const ModuleRawPtrConstRawPtr

Public Member Functions

virtual const ringmyBaseRing () const =0
virtual const ModuleElemmyZero () const =0
virtual void myInit (RawPtr &rawv) const =0
virtual void myInit (RawPtr &rawv, ConstRawPtr rawv1) const =0
virtual void myKill (RawPtr &rawv) const =0
virtual void mySwap (RawPtr &rawv, RawPtr &raww) const =0
virtual void myAssign (RawPtr &rawlhs, ConstRawPtr rawv) const =0
virtual void myNegate (RawPtr &rawlhs, ConstRawPtr rawv) const =0
virtual void myAdd (RawPtr &rawlhs, ConstRawPtr rawv, ConstRawPtr raww) const =0
virtual void mySub (RawPtr &rawlhs, ConstRawPtr rawv, ConstRawPtr raww) const =0
virtual void myMul (RawPtr &rawlhs, RingElemConstRawPtr rawx, ConstRawPtr rawv) const =0
virtual void myDiv (RawPtr &rawlhs, RingElemConstRawPtr rawx, ConstRawPtr rawv) const =0
virtual void myOutput (std::ostream &out, ConstRawPtr rawv) const =0
virtual void myOutputSelf (std::ostream &out) const =0
virtual void myOutput (OpenMathOutput &OMOut, ConstRawPtr rawv) const =0
virtual void myOutputSelf (OpenMathOutput &OMOut) const =0
virtual bool myIsZero (ConstRawPtr rawv) const =0
virtual bool myIsEqual (ConstRawPtr rawv, ConstRawPtr raww) const =0

Protected Member Functions

 ModuleBase ()
virtual ~ModuleBase ()
void myRefCountInc () const
 increments ref count
void myRefCountDec () const
 decrements ref count, and self destructs if count becomes 0
void myRefCountZero () const
 sets myRefCount to 0

Friends

class SmartPtrIRC< const ModuleBase >

Detailed Description

      Copyright (c)  2005 John Abbott
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.2;
      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
      A copy of the licence is included in the file COPYING in this directory.



User documentation for the classes module, ModuleBase, ModuleElem
=================================================================

You may also wish to look at the documentation for EFGModule
(which represents Explicitly Finitely Generated Modules).

The classes module, ModuleBase and ModuleElem are closely linked
together (analogously to the triple ring, RingBase, RingElem).

The class module is a reference counting smart pointer to a ModuleBase;
all concrete types of module are derived from ModuleBase.  For a library
implementor the class ModuleBase defines the minimal interface which
every concrete module class (i.e. derived from ModuleBase) must offer.

(1) Normal use of module and ModuleElem
---------------------------------------

A user of the CoCoA library who does not wish to add to the library need
know only what it is in this section.

Analogously to rings and RingElems, every ModuleElem belongs to some
module.  So before you can compute with ModuleElems you must create the
module(s) which contain them.

To create a module you must a pseudo-constructor for one of the concrete
module classes (refer to their documentation for details): e.g.
  NewFreeModule(R, n)   -- create a new FreeModule of n components over R


The functions which one may apply directly to a module are:
  NumCompts(M) -- the number of components an element of M has
  BaseRing(M)  -- the base ring of M (i.e. M is a module over this ring)
  gens(M)      -- a read only C++ vector containing the generators of M
  zero(M)      -- a read only ModuleElem which is the zero of M
  M1 == M2     -- are the two modules identical (same repr in memory)?
  M1 != M2     -- opposite of M1 == M2

As you can see there is not a lot one can do to a module.  Primarily
they exist to "give the correct type" to module elements; internally
they play a crucial role in applying operations to module elements.  A
C++ value of type ModuleElem represents an element of some concrete
module.  The module to which the value belongs is called the "owner" of
that value.  The owner of an object of type ModuleElem must be specified
(explicitly or implicitly) when it is created, and cannot be changed
during the lifetime of the object; the value it contains may, however,
be changed (C++ const rules permitting).


Functions on ModuleElems
------------------------

Let v be a non-const ModuleElem, and v1, v2 const ModuleElems all
belonging to the same concrete module M.  Let R be the base ring of M,
and r a const element of R.  Then we summarize the possible operations
using C++ syntax:

owner(v1)   // gives the module to which v1 belongs

-v1                                       // Usual arithmetic operations
v1 + v2                    v1 - v2        // between ModuleElems and
r * v1                     v1 * r         // RingElems.
                           v1 / r
v = v1
v += v1                    v -= v1
v *= r                     v /= r
v1 == v2                   v1 != v2
IsZero(v1)                 cout << v1

v[pos]  // throws if the module is not EFGModule 

In every case it is an error to combine/compare ModuleElems belonging
to different modules.


(2) Using raw values to go faster  [IGNORE THIS -- OUT OF DATE]
---------------------------------

The design of modules follows the design used for rings.  This means
that every operation on ModuleElems is actually effected by calling
the appropriate member function of the owning module.  These member
functions expect "raw values" as input.  A normal ModuleElem stores
within itself both the identity of the module to which it belongs and
its value as an element of that particular module -- we call the first
datum the "owner" and the second datum the "RawValue".  A RawValue can
be correctly interpreted only if supplied as argument to a member
function of the owning module -- calling module member functions for
an "incompatible" concrete module and RawValue will very likely have
grave consequences (officially stated as "undefined behaviour", and
most probably perceived as a program crash).

The member functions of a module DO NOT CHECK their arguments for being
sensible.  This decision is largely just a "design policy" imitating
that used for rings, but may also lead to some slight beneficial effect
on run-time performance.  It does naturally imply that the programmer
bears a considerable burden of responsibility.


(2.1) Member functions for operations on raw values  [IGNORE THIS -- OUT OF DATE]
---------------------------------------------------

For ring elements (especially those in a small finite field), noticeable
speed gains arise from using directly raw values and ring member
functions.  For modules the analogous effect exists in theory but will
likely be negligible in practice.  Nevertheless we list here the member
functions of a module; this list will be useful to library authors who
wish to create their own concrete module classes.

Let v be a non-const RawValue, and v1, v2 const RawValues belonging to M.
Let r be an RingBase::RawValue belonging to the base ring of M.

M.NumCompts()
M.BaseRing()
M.gens()        -- returns a const ref to a C++ vector of module:elems
M.zero()        -- returns a const ref to a ModuleElem

M.init(v)       -- allocates resources, apply only to uninitialized RawValue
M.init(v, v1)   -- allocates resources, apply only to uninitialized RawValue
M.kill(v)       -- releases resources
M.swap(v, w)
M.assign(v, v1)
M.negate(v, v1)
M.add(v, v1, v2)
M.sub(v, v1, v2)
M.mul(v, r, v1)
M.div(v, r, v1) -- NOTE funny arg order!
M.output(out, v1)
M.IsZero(v1)
M.IsEqual(v1, v2)


Maintainer documentation for the classes module, and ModuleElem
===============================================================

I shall suppose that the user documentation has already been read and
digested.  It could also be helpful to have read ring.txt since the
"design philosophy" here imitates that used for rings.

The class module is simply a reference counting smart pointer class to a
concrete module (i.e. an object belonging to a class derived from
ModuleBase).

A ModuleElem, like a RingElem, comprises two components: one specifying
the algebraic structure to which the value belongs, and the other being
an opaque representation of the value which can be correctly interpreted
only by the owning module.  The data members are:
  module myM;             // the module to which the ModuleElem belongs
  ModuleRawValue myValue; // "opaque" representation of the value,
                          // concrete modules must "import" this value.


Bugs, Shortcomings and other ideas
==================================

This code is too new, largely untried/untested.  As soon as it gets
some use, there will be some material to put here :-)

The documentation is limited and rather old.  Will be fixed (eventually).
Maintainer documentation is virtually absent.

Definition at line 86 of file module.H.


Member Typedef Documentation

typedef ModuleRawPtr CoCoA::ModuleBase::RawPtr
 

Reimplemented in CoCoA::EFGModuleBase.

Definition at line 94 of file module.H.

typedef const ModuleRawPtr& CoCoA::ModuleBase::ConstRawPtr
 

Reimplemented in CoCoA::EFGModuleBase.

Definition at line 95 of file module.H.


Constructor & Destructor Documentation

CoCoA::ModuleBase::ModuleBase  )  [inline, protected]
 

Definition at line 193 of file module.H.

References CoCoA::IntrusiveReferenceCount::myRefCountInc().

virtual CoCoA::ModuleBase::~ModuleBase  )  [protected, virtual]
 


Member Function Documentation

virtual const ring& CoCoA::ModuleBase::myBaseRing  )  const [pure virtual]
 

virtual const ModuleElem& CoCoA::ModuleBase::myZero  )  const [pure virtual]
 

virtual void CoCoA::ModuleBase::myInit RawPtr rawv  )  const [pure virtual]
 

virtual void CoCoA::ModuleBase::myInit RawPtr rawv,
ConstRawPtr  rawv1
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myKill RawPtr rawv  )  const [pure virtual]
 

virtual void CoCoA::ModuleBase::mySwap RawPtr rawv,
RawPtr raww
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myAssign RawPtr rawlhs,
ConstRawPtr  rawv
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myNegate RawPtr rawlhs,
ConstRawPtr  rawv
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myAdd RawPtr rawlhs,
ConstRawPtr  rawv,
ConstRawPtr  raww
const [pure virtual]
 

virtual void CoCoA::ModuleBase::mySub RawPtr rawlhs,
ConstRawPtr  rawv,
ConstRawPtr  raww
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myMul RawPtr rawlhs,
RingElemConstRawPtr  rawx,
ConstRawPtr  rawv
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myDiv RawPtr rawlhs,
RingElemConstRawPtr  rawx,
ConstRawPtr  rawv
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myOutput std::ostream &  out,
ConstRawPtr  rawv
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myOutputSelf std::ostream &  out  )  const [pure virtual]
 

virtual void CoCoA::ModuleBase::myOutput OpenMathOutput OMOut,
ConstRawPtr  rawv
const [pure virtual]
 

virtual void CoCoA::ModuleBase::myOutputSelf OpenMathOutput OMOut  )  const [pure virtual]
 

virtual bool CoCoA::ModuleBase::myIsZero ConstRawPtr  rawv  )  const [pure virtual]
 

virtual bool CoCoA::ModuleBase::myIsEqual ConstRawPtr  rawv,
ConstRawPtr  raww
const [pure virtual]
 

void CoCoA::IntrusiveReferenceCount::myRefCountInc  )  const [inline, protected, inherited]
 

increments ref count

Definition at line 86 of file SmartPtrIRC.H.

Referenced by ModuleBase().

void CoCoA::IntrusiveReferenceCount::myRefCountDec  )  const [inline, protected, inherited]
 

decrements ref count, and self destructs if count becomes 0

Definition at line 91 of file SmartPtrIRC.H.

void CoCoA::IntrusiveReferenceCount::myRefCountZero  )  const [inline, protected, inherited]
 

sets myRefCount to 0

Definition at line 97 of file SmartPtrIRC.H.


Friends And Related Function Documentation

friend class SmartPtrIRC< const ModuleBase > [friend]
 

Definition at line 88 of file module.H.


The documentation for this class was generated from the following file:
Generated on Wed May 23 13:46:22 2007 for CoCoALib by  doxygen 1.4.6