The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Algorithm-MasterMind-v0.4.5
River stage zero No dependents
2 ++
/ Algorithm::MasterMind

NAME

Algorithm::MasterMind - Framework for algorithms that solve the MasterMind game

VERSION

This document describes Algorithm::MasterMind version 0.4.1

SYNOPSIS

    use Algorithm::MasterMind;
    use Algorithm::MasterMind::Solver; # Change "solver" to your own.

    my $solver = new Algorithm::MasterMind::Solver $options; 

    my $first_string = $solver->issue_first();
    $solver->feedback( check_combination( $secret_code, $first_string) );

    my $played_string = $solver->issue_next;
    $solver->feedback( check_combination( $secret_code, $played_string) );

    #And so on until solution is found

DESCRIPTION

Includes common functions used in Mastermind solvers; it should not be used directly, but from derived classes. See examples in Algorithm::MasterMind::Random, for instance.

INTERFACE

new ( $options )

Normally to be called from derived classes

add_rule( $combination, $result)

Adds a rule (set of combination and its result as a hash) to the set of rules. These rules represent the information we've got on the secret code.

check_combination( $secret_code, $combination )

Checks a combination against the secret code, returning a hashref with the number of blacks (correct in position) and whites (correct in color, not position)

distance( $object )

Computes distance to a consistent combination, computed as the number of blacks and whites that need change to become a consistent combination.

check_combination_old ( $secret_code, $combination )

Old way of checking combinations, eliminated after profiling

check_rule ($rule, $combination)

Same as check_combination, except that a rule contains a combination and how it scored against the secret code

issue_first ()

Issues the first combination, which might be generated in a particular way

start_from ()

Used when you want to create an solver once it's been partially solved; it contains partial solutions.

issue_first_Knuth

First combination looking like AABC for the normal mastermind. Proposed by Knuth in one of his original papers.

issue_next()

Issues the next combination

feedback()

Obtain the result to the last combination played

guesses()

Total number of guesses

evaluated()

Total number of combinations checked to issue result

number_of_rules ()

Returns the number of rules in the algorithm

rules()

Returns the rules (combinations, blacks, whites played so far) as a reference to array

matches( $string )

Returns a hash with the number of matches, and whether it matches every rule with the number of blacks and whites it obtains with each of them

hashify ( $string )

Turns a string into a hash, to help with comparisons. Used internally, mainly.

not_in_combination( $string)

Returns the letters from the alphabet that are _not_ in this combination. Might be useful for certain strategies.

random_combination

Combines randomly the alphabet, issuing, you guessed it, a random combination.

partitions

From a set of combinations, returns the "partitions", that is, the number of combinations that would return every set of black and white response. Inputs an array, returns a hash keyed to the combination, each key containing a value corresponding to the number of elements in each partition.

all_combinations

Returns all possible combinations of the current alphabet and length in an array. Be careful with that, it could very easily fill up your memory, depending on length and alphabet size.

entropy( $string )

Computes the string entropy

distance_taxicab( $string )

Computes the sums of taxicab distances to all combinations in the game, and returns it as [$distance, $matches]

distance_chebyshev( $string )

Computes the Chebyshev distance, that is, the max of distances in all dimensions. Returns as a arrayref with [$distance, matches]

all_responses()

Returns all possible responses (combination of black and white pegs) for the combination length

random_string

Returns a random string in with the length and alphabet defined

response_as_string ( $response )

From a hash that uses keys blacks and whites, returns a string "xb-yw" in a standard format that can be used for comparing.

CONFIGURATION AND ENVIRONMENT

Algorithm::MasterMind requires no configuration files or environment variables.

DEPENDENCIES

Algorithm::Evolutionary, but only for one of the strategies. Algorithm::Combinatorics, used to generate combinations and for exhaustive search strategies.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-algorithm-mastermind@rt.cpan.org, or through the web interface at http://rt.cpan.org.

SEE ALSO

Other modules in CPAN which you might find more useful than this one are at Games::Mastermind::Solver, which I didn't use and extend for no reason, although I should have. Also Games::Mastermind::Cracker.

Formerly, you could try and play this game at http://geneura.ugr.es/~jmerelo/GenMM/mm-eda.cgi, restricted to 4 pegs and 6 colors. It's, for the time being, under reparations. The program mm-eda.cgi should also be available in the apps directory of this distribution.

The development of this projects is hosted at sourceforge, https://sourceforge.net/projects/opeal/develop, check it out for the latest bleeding edge release. In fact, right now this module is at least a year away from the latest development.

If you use any of these modules for your own research, we would very grateful if you would reference the papers that describe this, such as this one:

 @article{merelo2010finding,
  title={{Finding Better Solutions to the Mastermind Puzzle Using Evolutionary Algorithms}},
  author={Merelo-Guerv{\'o}s, J. and Runarsson, T.},
  journal={Applications of Evolutionary Computation},
  pages={121--130},
  year={2010},
  publisher={Springer}
 }

or

 @inproceedings{DBLP:conf/cec/GuervosMC11,
  author    = {Juan-J. Merelo-Guerv{\'o}s and
               Antonio-Miguel Mora and
               Carlos Cotta},
  title     = {Optimizing worst-case scenario in evolutionary solutions
               to the {MasterMind} puzzle},
  booktitle = {IEEE Congress on Evolutionary Computation},
  year      = {2011},
  pages     = {2669-2676},
  ee        = {http://dx.doi.org/10.1109/CEC.2011.5949952},
  crossref  = {DBLP:conf/cec/2011},
  bibsource = {DBLP, http://dblp.uni-trier.de}
 }

 @proceedings{DBLP:conf/cec/2011,
  title     = {Proceedings of the IEEE Congress on Evolutionary Computation,
               CEC 2011, New Orleans, LA, USA, 5-8 June, 2011},
  booktitle = {IEEE Congress on Evolutionary Computation},
  publisher = {IEEE},
  year      = {2011},
  isbn      = {978-1-4244-7834-7},
  ee        = {http://ieeexplore.ieee.org/xpl/mostRecentIssue.jsp?punumber=5936494},
  bibsource = {DBLP, http://dblp.uni-trier.de}
 }

AUTHOR

JJ Merelo <jj@merelo.net>

LICENCE AND COPYRIGHT

Copyright (c) 2009, JJ Merelo <jj@merelo.net>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.