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, 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.