=head1 NAME

C<Math::Macopt> - provides PERL interface for the B<macopt> C++ codes, 
which is developed by David Mackay. 
L<http://www.inference.phy.cam.ac.uk/mackay/c/macopt.html>

=head1 INSTALLATION

The package can be installed by the standard PERL module installation procedure:

  perl Makefile.PL
  make
  make test
  make install

Please noted that the original "macopt" C++ source code is included in this 
PERL package. The static linking avoids any conflict if you have installed
previous version of "macopt".

=head1 SYNOPSIS

  use strict;
  use Math::Macopt;
  
  &main();
  
  sub main
  {
  	# Some settings
  	my $N = 10;
  	my $epsilon = 0.001;
  
  	# Initialize the Macopt 
  	my $macopt = new Math::Macopt::Base($N, 0);
  
  	# Setup the function and its gradient
   	my $func = sub {
  		my $x = shift;
  
  		my $size = $macopt->size();
   		my $sum = 0;
   		foreach my $i (0..$size-1) {
   			$sum += ($x->[$i]-$i)**2;
   		}
   		
  		return $sum;
   	};
   	my $dfunc = sub {
   		my $x = shift;
  
  		my $size = $macopt->size();
   		my $g = ();
   		foreach my $i (0..$size-1) {
   			$g->[$i] = 2*($x->[$i]-$i); 
   		}
   
   		return $g;
   	};
  	$macopt->setFunc(\&$func);
  	$macopt->setDfunc(\&$dfunc);
  
  	# Optimizer using macopt 
  	my $x = [(1)x($N)];
  	$macopt->maccheckgrad($x, $N, $epsilon, 0) ;
  	$macopt->macoptII($x, $N);

	# Display the result
	printf "[%s]\n", join(',', @$x);
  }

=head1 DESCRIPTION
  
=head2 Overview

The C<Math::Macopt> is generated by SWIG (L<http://www.swig.org>) 
to provide PERL API to the native C macopt codes.

=head2 Class Hierarchy

  Math::Macopt
  +- Math::Macopt::Base

=head2 Constants

nil.

=head2 Member Variables

nil.

=head2 Constructor and initialization

=over

=item C<new>

Same as the original C++ source code.

Arguments:

=over

=item *

0: (Integer) n -- The dimension of the vector.

=item *

1: (Boolean) verbose -- Whether the verbose messages are displayed.

=item *

2: (Double) tolerance -- Optimization convergence.

=item *

3: (Boolean) rich -- Whether to do extra gradient evaluation.

=back

Returns:

=over

=item *

The blessed object.

=back

Please refer to the original macopt code for details.

=back

=head2 Class and Object methods

=over

=item C<size>

Arguments:

=over

=item *

nil.

=back

Returns:

=over

=item *

(Integer) The number of dimensions.

=back

=item C<macoptII>

Optimize (minimize) the vector based on the function and its gradient.

Arguments:

=over

=item *

0: (ARRAY) x -- Starting vector.

=item *

1: (Integer) N -- The number of dimensions.

=back

Returns:

=over

=item *

nil.

=back

Please notice that the optimal results will be put in the
input vector "x" after called.

=item C<maccheckgrad>

Examines objective function and d_objective function to see if 
they agree for a step of size epsilon. 

Arguments:

=over

=item *

0: (ARRAY) x -- Starting vector.

=item *

1: (Integer) N -- The number of dimensions.

=item *

2: (Double) eplison -- Step size. 

=item *

3 (Boolean) stopat -- Stop at this component. If 0, do the lot. 

=back

Returns:

=over

=item *

nil.

=back

=item C<setFunc>

=item C<setDfunc>

Set the function and its gradient function as PERL callbacks.

Arguments:

=over

=item *

0: (SV*) callback -- The PERL callback.

=back

Returns:

=over

=item *

nil.

=back

=back

=head1 OTHER ISSUES

=head2 Future Plans 

=over

=item *

Support on MS Windows (e.g., SFU or native)

=item *

Support on Java language (e.g., use SWIG for Java)

=back

=head1 BUGS

No bug found yet.

=head1 RELATED MODULES

nil.

=head1 AUTHOR(S)

Tom Chau <tom@cpan.org>

=head1 CREDIT(S)

Cluster Technology Limited L<http://www.clustertech.com>

=cut
