Contributing to Math-DifferenceSet-Planar
=========================================

Thank you for your interest in contributing to this Perl 5
library.  Currently, it is in active development and maintained
by its original author.  Bug reports (with or without patch),
suggestions, feature requests, and comments are welcome.  You may
submit them through this distribution's bug tracker on github:
https://github.com/mhasch/perl-Math-DifferenceSet-Planar/issues

You can also reach the author by e-mail:
Martin Becker, <becker-cpan-mp (at) cozap.com>

The code for this distribution is hosted at GitHub.  The repository is:
https://github.com/mhasch/perl-Math-DifferenceSet-Planar

If your contribution is accepted, you will be mentioned by name under
ACKNOWLEDGEMENTS in the documentation.  Please indicate if you prefer
an alias or to stay anonymous.

Data extensions are currently hosted on GitHub, too, but urgently
need a more cost-efficient download location than that.  Expect
an announcement as well as new data before long.

Development Guidelines
----------------------

This library, dealing with a mathematical concept, should first and
foremost be scientifically sound.  Correctness is rated over all other
quality aspects.  The second most important goal is a documentation and
over-all presentation that makes it useful for experts and informative
for anybody interested in the field.  Thirdly, it should be easy to
integrate correctly and efficiently with other software.

Topics of Interest
------------------

Planar difference sets are special entities described in the theory
of difference sets, which is a part of design theory, which in turn
is related to algebra, geometry, and combinatorics.  They are also
the essence of Desarguesian finite projective planes (unlike other
difference sets).

Possible improvements of the software may support interoperability with
related, or more general, or application software.  New interfaces such as
a command line tool, an interactive tool, or a web service may be added
as well.  The functionality of the scripts in the examples directory
may be included in such tools.  More ways to present difference sets,
especially graphically, could be a nice addition.

We also want to add more functionality for geometric aspects, like
line intersection, collinearity, and coordinate mapping.

An XS implementation could increase performance with large sets.
Computation of more data will be included as soon as a prerequisite Perl
library, Math-GaloisField, is publicly available.

An interface to remote databases may provide a good alternative to
distributing ever larger databases for local use.

As it can be expected that downloading sets will always be faster than
generating them, a non-programmer contribution could be to host a large
database of sample sets.  Especially helpful would be a solution that even
allows to submit more data.  The author so far has collected and published
sets with all orders up to 2 ** 17 and some single examples up to
2 ** 23.  Extending this list would require massive computing power
and be conceivable as a project for distributed computation.  Not much
scientific merit, alas, is going to be earned for such an effort, as the
existence as well as most of the "interesting" properties of these sets
are already known facts.  Future applications of planar difference sets,
however, might benefit from larger sample sets than currently available.

On the other hand, the data already present requires double- and perhaps
triple-checking before it can be regarded as scientifically acceptable.
For each order, we used Singer's construction to generate a sample set,
wich is provably valid, and iterated through its multiples to find
reference sets with their respective optimality properties.

Better scripts to generate the data should be included in the examples
collection to aid verification and extension.

The documentation, finally, could include more literature, or be clearer
or better formatted.  We might create POD, HTML, and PDF from a common
source.

So much for programmatic and technical contributions.  Topical
contributions could review literature on the subject to spot important
aspects not yet incorporated or not represented in their current status.
It is also quite conceivable to make progress in the theory itself through
further research.  As noted elsewhere, the theory of finite projective
planes and hence planar difference sets is abundant with conjectures
widely believed to be true but withstanding rigorous proof so far.
This could be taken as signs of imminent breakthrough discoveries, or,
at least, important puzzle pieces still missing.

Git Repositories
----------------

The Math-DifferenceSet-Planar project is maintained in these git
repositories:

* perl-Math-DifferenceSet-Planar

  The base library with everything needed to create its CPAN distribution.
  Also the place where changes and new features are discussed.

* perl-Math-DifferenceSet-Planar-Data-M

  An extension that deploys a somewhat larger database of precomputed
  data to a place where it will be found by the base library.

* perl-Math-DifferenceSet-Planar-Data-L

  An extension that deploys a significantly larger database of precomputed
  data to a place where it will be found by the base library.  It covers
  all orders that can be handled with 32-bit integer arithmetic.

* perl-Math-DifferenceSet-Planar-Data-XL

  An extension that deploys the largest currently available database of
  precomputed data to a place where it will be found by the base library.

Users of the Module Math::DifferenceSet::Planar will need the base library
and optionally one of the M/L/XL data extensions.  The data extensions are
not intended to be uploaded to CPAN, to save bandwitdth and storage space.
Maintainers will need the git repositories.

Development Platform
--------------------

CPAN releases of this library are currently prepared manually with
scripts in the maint directory and ExtUtils::MakeMaker.  A migration to
a distribution builder like Dist::Zilla may be performed in the future.

The git repository contains these files the CPAN release does not:

.gitignore
compute/even_order_sample.c
compute/extra_large_sample.gp
compute/prime_order_samples.gp
maint/create_cpan_db
maint/create_extra_db
maint/create_larger_dbs
maint/create_test_db
maint/dump_pds_old
maint/dump_spaces
maint/fill_pds
maint/fill_spaces
maint/make_pod
maint/template-1.1.pod
maint/template-2.0.pod
maint/template.pod

The dump scripts generate text representations of the database contents,
while the fill scripts generate database contents from plaintext input.
Only the databases are included in repositories as they are more terse.

As the database schema has changed with release 1.000 of the library,
we have included a script to dump the contents of an old-style database
that might be handy for a migration.  Dumping new-style databases is
already covered in the pds_iterate_* example scripts.

The compute folder contains helper scripts in other languages to
generate data from scratch.  Ultimately, the library should become
capable of self-reproducing.

Author's Note
-------------

Thanks again for your interest.
I am looking forward to your report or e-mail.

Martin Becker, July 14, 2024.