MeatAxe: Permutations

MeatAxe 2.4

- Main Page
- Related Pages
- Modules
- Data Structures

Data Structures | Functions
Permutations

## Detailed Description

In the MeatAxe, a permutation of degree n operates on {0,1,...,n-1} and is represented by a Perm_t structure. However, in the textual representation produced by PermPrint() or by the zpr program, the points are numbered from 1...n.

Only permutations of equal degree can be multiplied. This could cause confusion because the textual representation produced by PermPrint() does not include the degree, and fixed points are always suppressed. For example "(3 4)(5 6 7)" could be interpreted as a permutation of degree 8 or any higher degree. All these permutations are in some natural way equal to each other, but they are different and incompatible in the MeatAxe.

Permutations are usually created with PermAlloc() or read from a file with PermRead(). When a permutation is no longer used, the application must release the associated memory by calling PermFree().

## Data Structures
class | Perm_t
| A Permutation. More...
## Functions
int | PermCompare (const Perm_t *a, const Perm_t *b)
| Compare two permutations.
int | PermIsValid (const Perm_t *p)
| Check a permutation.
Perm_t * | PermAlloc (int deg)
| Allocate a permutation This function creates a permutation of the specified degree.
int | PermFree (Perm_t *p)
| Free a permutation.
Perm_t * | PermDup (const Perm_t *src)
| Duplicate a permutation.
Perm_t * | PermInverse (const Perm_t *src)
| Inverse of a permutation This function calulates the inverse of a permutation.
Perm_t * | PermMul (Perm_t *dest, const Perm_t *src)
| Multiply permutations.
int | PermOrder (const Perm_t *perm)
| Order of a permutation.
void | PermPrint (const char *name, const Perm_t *perm)
| Print a permutation This function prints a permutation on the standard output using cycle notation.
Perm_t * | PermPower (const Perm_t *p, int n)
| Power of a permutation This function calculates the n-th power of a permutation.
Perm_t * | PermRead (FILE *f)
| Read a Permutation from a File.
Perm_t * | PermLoad (const char *fn)
| Read a permutation.
int | PermWrite (const Perm_t *perm, FILE *f)
| Write a Permutation to a File.
int | PermSave (const Perm_t *perm, const char *fn)
| Write a Permutation to a File.

## Function Documentation

Perm_t* PermAlloc | ( | int | deg | ) |

Allocate a permutation This function creates a permutation of the specified degree.

The new permutation is initialized to the identity.

Parameters:

  deg | Degree.

Returns:
  Pointer to the new permutation, or 0 on error.

int PermCompare | ( | const Perm_t * | a,
|  | const Perm_t * | b
| ) |  |

Compare two permutations.

This function compares two permutations. If the permutations are equal, the return value is 0. Otherwise the return value is positive if a is "greater" than b, and negative if a is "less" than b. The ordering of permutations is defined as follows. If the permutations have different degrees, the permutations with the smaller degree is smaller. Otherwise, the result of the comparison is unspecified.

Note that the return value -1 does not necessarily mean that an error occured.

Parameters:

  a | Pointer to the first permutation.
  b | Pointer to the second permutation.

Returns:
  0, if the matrices are equal, a nonzero value otherwise, -1 on error.

Perm_t* PermDup | ( | const Perm_t * | src | ) |

Duplicate a permutation.

This function creates a copy of an existing permutation.

Parameters:

  src | Pointer to the permutation.

Returns:
  Pointer to a copy of src or 0 on error.

int PermFree | ( | Perm_t * | p | ) |

Free a permutation.

This function deletes a permutation and returns the memory to the system. Do not use SysFree() on permutations because this would only free the Perm_t structure but not the data buffer.

Parameters:

  p | Pointer to the permutation.

Returns:
  0 on success, -1 on error.

Perm_t* PermInverse | ( | const Perm_t * | src | ) |

Inverse of a permutation This function calulates the inverse of a permutation.

Parameters:

  src | Pointer to the permutation.

Returns:
  The inverse of src, or 0 on error.

int PermIsValid | ( | const Perm_t * | p | ) |

Check a permutation.

This function checks if the argument, is a pointer to a valid permutation. If the permutation is o.k., the function return 1. Otherwise, an error is signalled and, if the error handler does not terminate the program, the function returns 0.

Returns:
  1 if p is valid permutation, 0 otherwise.

Perm_t* PermLoad | ( | const char * | fn | ) |

Read a permutation.

This function opens a file, reads a single permutation, and closes the file. The return value is a pointer to the permutation or 0 on error. If the file contains more than one permutation, only the first one is read. If a permutation was successfully read, the function returns a pointer to a newly created Perm_t object. The caller is responsible for deleting this object as soon as the permutation is no longer needed.

See also:
  PermRead()

Parameters:

  fn | File name.

Returns:
  Pointer to the permutation read from the file, or 0 on error.

Perm_t* PermMul | ( | Perm_t * | dest,
|  | const Perm_t * | src
| ) |  |

Multiply permutations.

This function multiplies dest from the right by src. Both permutations must have the same degree.

Parameters:

  dest | Pointer to the first permutation.
  src | Pointer to the second permutation.

Returns:
  dest, or 0 on error.

int PermOrder | ( | const Perm_t * | perm | ) |

Order of a permutation.

Parameters:

  perm | Pointer to the permutation.

Returns:
  The order of 0, or -1 on error.

Perm_t* PermPower | ( | const Perm_t * | p,
|  | int | n
| ) |  |

Power of a permutation This function calculates the n-th power of a permutation.

It allocates a new permutation, leaving the original permutation intact. The caller is responsible for deleting the result when it is no longer needed.

Parameters:

  p | Pointer to the permutation.
  n | Exponent. Must be greather than or equal to 0.

Returns:
  n-th power of p or 0 on error.

void PermPrint | ( | const char * | name,
|  | const Perm_t * | perm
| ) |  |

Print a permutation This function prints a permutation on the standard output using cycle notation.

If name is not 0, the name followed by an equal sign is printed before the permutation. For example, the statement `PermPrint("Perm",P);` could produce the following output:

     Perm=(1 9)(2 3 6)(4 5 7)

Fixed points are always suppressed in the output.

Parameters:

  name | Name to print before the permutation or 0.
  perm | Pointer to the permutation.

Returns:
  The function returns 0 on success and -1 on error.

Perm_t* PermRead | ( | FILE * | f | ) |

Read a Permutation from a File.

This function reads a permutation from a file. f must be a pointer to an open file with read permission. If a permutation was successfully read, the function returns a pointer to a newly created Perm_t object. The caller is responsible for deleting this object as soon as the permutation is no longer needed.

See also:
  PermLoad()

Parameters:

  f | File to read from.

Returns:
  Pointer to the permutation, or 0 on error.

int PermSave | ( | const Perm_t * | perm,
|  | const char * | fn
| ) |  |

Write a Permutation to a File.

This function creates a file, writes a single permutation to the file and closes the file. If a file with the specified name already exists, its contents are destroyed.

See also:
  PermWrite

Parameters:

  perm | Permutation to write.
  fn | File name.

Returns:
  The function returns 0 on success and -1 on error.

int PermWrite | ( | const Perm_t * | perm,
|  | FILE * | f
| ) |  |

Write a Permutation to a File.

This function writes a permutation to a file. The file must be open for writing.

See also:
  PermSave

Parameters:

  perm | Permutation to write.
  f | File to write to.

Returns:
  The function returns 0 on success and -1 on error.