Documentation:The palps Python modules

From ALPS
Jump to: navigation, search

The ALPS Python modules

The ALPS Python module is called pyalps and can be imported using

import pyalps

In addition to the main module pyalps there exist two submodules pyalps.plot, pyalps.alea and pyalps.math that contain plotting and Monte Carlo data evaluation tools. On this Wiki page we list the functions provided in these modules. To access the documentation of a function like writeInputFiles, just use the Python documentation system:

import pyalps
print pyalps.writeInputFiles.__doc__

The pyalps module

The module pyalps contains most of the ALPS Python functions.

Functions to run and evaluate simulations

Preparing the input

  • writeInputFiles
  • writeParameterFile

Running the simulation

  • runApplication
  • runDMFT

Running the evaluation tools

  • evaluateLoop
  • evaluateSpinMC
  • evaluateQWL
  • evaluateFulldiagVersusT
  • evaluateFulldiagVersusH

Loading and evaluating results

Getting the result files

  • getResultFiles

Loading results from result files

  • loadObservableList
  • loadProperties
  • loadSpectra
  • loadEigenstateMeasurements
  • loadMeasurements
  • loadBinningAnalysis

Checking equilibration

Checking convergence

  • checkConvergence

Evaluating results

  • collectXY
  • groupSets
  • subtract_spectrum

Miscellaneous tools

  • save_parameters
  • dict_intersect
  • convert2xml: this function takes a list of ALPS binary files and converts them to XML
  • hdf5_name_encode: this function encodes a string passed as argument and returns a string where any / character is escaped, so that the name can be used as an HDF5 path name
  • hdf5_name_decode: this function decodes a string passed as argument, replacing any escaped sequence


Classes

The DataSet class

The DataSet class is the main class used in ALPS to represent results of simulations. It is a very simple class containing three members:

  • props: a Python dict storing the parameters and other properties
  • x: the x-values in plots or the index in array-valued measurements
  • y: the y-values in plots or the values of the measurements

The rng class

The rng class exposes the Boost Mersenne Twister random number generator to Python. It has two member function:

  • The constructor takes an optional integer seed argument
  • The function call operator returns a random number in the interval [0,1)

Example:

import pyalps
g = pyalps.rng(42)
print g()
print g()

The pyalps.plot module

This module contains functions for creating matplotlib, Grace or Gnuplot plots and for converting a plot description to plain text

  • plot
  • makeGracePlot
  • makeGnuplotPlot
  • convertToText

The first function creates a plot, while the others return a string with the Grace, Gnuplot script or a textual representation of the data

An example of using the DataSet and plotting functions can be found here

The pyalps.hdf5 module

This module contains HDF5 archive classes:

  • oArchive: class to write data to file
  • iArchive: class to read data from file

with the API

  1. template<typename Archive> struct pyarchive {
  2.  
  3.     string filename() const;
  4.     bool is_group(string const & path) const;
  5.     bool is_data(string const & path) const;
  6.     bool is_attribute(string const & path) const;
  7.     bool is_scalar(string const & path) const;
  8.     bool is_string(string const & path) const;
  9.     bool is_null(string const & path) const;
  10.     bool dimensions(string const & path) const;
  11.     list<int> extent(string const & path) const;
  12.     list<string> list_children(string const & path) const;
  13.     list<string> list_attr(string const & path) const;
  14. };
  15.  
  16. struct pyoarchive : public pyarchive<alps::hdf5::oarchive> {
  17.     pyoarchive(string const & filename) {}
  18.     pyoarchive(pyoarchive const & rhs) {}
  19.     void write(string const & path, mixed const & data);
  20. };
  21.  
  22. struct pyiarchive : public pyarchive<alps::hdf5::iarchive> {
  23.     pyiarchive(string const & filename);
  24.     pyiarchive(pyiarchive const & rhs);
  25.     mixed read(string const & path);
  26. };

Example of writing data to a HDF5 file

  1. import pyalps.hdf5 as h5
  2.  
  3. ar = h5.oArchive('test.h5')
  4. ar.write('/path/to/data',2500)
  5. ar.write('/path/to/string','Hello World')
  6.  
  7. import numpy as np
  8. vec = np.array([0, 1, 2, 3])
  9. ar.write('/path/to/vector/data', vec)

Example of reading data from a HDF5 file

  1. import pyalps.hdf5 as h5
  2.  
  3. ar = h5.iArchive('test.h5')
  4. data = ar.read('/path/to/data')

The pyalps.alea module

This module contains the ALPS classes for Monte Carlo data evaluation. The classes

  • MCRealObservable
  • MCRealVectorObservable

are used to collect MC measurements and write the result to an ALPS HDF5 file. The classes

  • MCScalarData
  • MCVectorData

are used to load results from an ALPS HDF5 file and evaluate the results

Recording measurements

The MCRealObservable and MCRealVectorObservable classes are used to record Monte Carlo measurements. The MCRealObservable accepts floating point values, while the MCRealVectorObservable accepts one-dimensional numpy arrays of floating point numbers.

It has the following members:

  • the constructor takes a string argument, the name of the observable, and an optional second integer argument specifying the maximum number of bins to be recorded.
  • << : the left shift operator is used to record new measurements
  • the following read-only properties exist to access the results of measurements:
    • mean
    • error
    • tau
    • variance
    • count
  • save(filename): writes the measurements into the HDF5 file whose name is given

Evaluating measurements: the MC Data class

Monte Carlo data is loaded from HDF5 files into DataSet objects. The values are stores as MCData objects of which there are three types:

  • MCScalarData
  • MCVectorData
  • VectorOfMCData

All of these classes have the following members:

  • mean
  • error
  • tau
  • variance
  • count

In addition these classes implement all arithmetic operations +, -, *, /, +=, -=, *=, and /=. They also implement the following functions as member functions, or as free functions through the pyalps.math module:

  • sq
  • sqrt
  • cb
  • cbrt
  • exp
  • log
  • sin
  • cos
  • tan
  • asin
  • acos
  • atan
  • sinh
  • cosh
  • tanh
  • asinh
  • acosh
  • atanh

Now to the differences. MCScalarData is for floating point values while MCVectorData and VectorOfMCData are for one-dimensional arrays of floating point values. MCVectorData is an optimized class acting on the whole array. subscript and array operations are possible on the results (mean, error, ….) but not on the object itself. VectorOfMCData on the other hand is an array of MCScalarData objects, but is slower.

By default the ALPS functions load an array-valued measurement into an MCVectorData object. There exists a function

  • MCVectorData2VectorOfMCData

to convert one to the other.

The pyalps.math module

This module contains a number of mathematical functions, which dispatch to the appropriate math, numpy, or alps function depending on the type of argument. They can thus be used with floating point numbers, array, and ALPS MC Data objects. The functions are:

  • sq
  • sqrt
  • cb
  • cbrt
  • exp
  • log
  • sin
  • cos
  • tan
  • asin
  • acos
  • atan
  • sinh
  • cosh
  • tanh
  • asinh
  • acosh
  • atanh