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 CPAN RT:
https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-DifferenceSet-Planar

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.

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 already has collected sets
with orders up to seven figures.  Extending this to a list covering
all orders up to, say, 2 ** 21 would require thousands of CPU years,
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.

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

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

CPAN releases of this library are currently prepared manually with
scripts in the maint directory and ExtUtils::MakeMaker.  A switch 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
maint/create_cpan_db
maint/create_extra_db
maint/create_large_db
maint/create_test_db
maint/dump_pds
maint/fill_pds
maint/make_pod
maint/template.pod

To create the databases in the share and t/db directories of the CPAN
distribution, as well as some larger databases not for CPAN, you also
need these files:

data/extra_2096993.txt
data/pdm_00002-04096.txt
data/pdm_04099-10993.txt
data/pdx_000002-004096.txt
data/pdx_004099-008192.txt
data/pdx_008209-012289.txt
data/pdx_012301-016384.txt
data/pdx_016411-020483.txt
data/pdx_020507-024571.txt
data/pdx_024593-028669.txt
data/pdx_028687-032771.txt
data/pdx_032779-036871.txt
data/pdx_036877-040961.txt
data/pdx_040973-045061.txt
data/pdx_045077-049157.txt
data/pdx_049169-053239.txt
data/pdx_053267-057349.txt
data/pdx_057367-061441.txt
data/pdx_061463-065551.txt
data/pdx_065557-069623.txt
data/pdx_069653-073727.txt
data/pdx_073751-077839.txt
data/pdx_077849-081937.txt
data/pdx_081943-086029.txt
data/pdx_086069-090127.txt
data/pdx_090149-094229.txt
data/pdx_094249-098327.txt
data/pdx_098347-102409.txt
data/pdx_102433-106501.txt
data/pdx_106531-110609.txt
data/pdx_110623-114713.txt
data/pdx_114743-118801.txt
data/pdx_118819-122891.txt
data/pdx_122921-126989.txt
data/pdx_127031-131101.txt

These text representations of planar difference sets are distributed
separately in order not to bloat the software repository.  They occupy
8.2 GB of storage.  A download location is yet to be determined.
Please contact the author if you urgently need the data or want to help.

For convenience, a subset sufficient to create the CPAN release is
included in the git repository.

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

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

Martin Becker, January 1, 2021.