Tutorials/Contributing to Catagolue

So you've decided to contribute to Adam P. Goucher (Calcyman)'s Catagolue. Excellent! Are you familiar with cellular automata yet? If no, you may want to read the rules tutorial first, but this is optional.

Generating a Payosha256 key

If you want to contribute anonymously, you can skip this section.

If you want to contribute under your name or a pseudonym, you will have to create a Payosha256 key. (Payosha256 is a protocol based on Adam Back's HashCash proof-of-work system).

In order to generate a Payosha key, you need to be logged into a Google account; create a new one if you don't have one or don't want to use your existing one. If you can't or don't want to do this, you'll not be able to contribute to Catagolue non-anonymously.

Go to Catagolue's Payosha256 page, log in using the login link, and authorize Catagolue. Once you're logged in and back on Catagolue, create a new key/displayed name pair. The key itself can be chosen by you and should be kept safe, the same way a password would. Contributions made using the key will carry the displayed name you provided.

You can create as many keys as you'd like. (But you won't need more than one.)

The unofficial Twitter bot

Significant discoveries in Conway's Game of Life (B3/S23) are automatically reported on the independently-operated conwaylife Twitter bot account, and credited to you if they're from asymmetric soups. If your displayed name starts with an @ sign, it will be considered a Twitter username.

If your displayed name does not start with an @ sign, codeholic (the maintainer/operator of the Twitter bot) can map your displayed name to your Twitter user name. Send him a PM on the Conway Life forums (or otherwise get in touch with him) to have this done.

Your Catagolue user page

Your Catagolue user page tracks your contributions for B3/S23/C1, awards badges for certain achievements, and displays your findings.

Unlike on the unofficial Twitter bot account, your findings include any of the first 20 occurrences of any oscillator with period greater than 2, and any spaceship or yl pattern. For oscillators with period 2 and "interesting" still lives (above a certain population or precursors of important patterns), only the first occurrence is credited. Other still lives, zz patterns and PATHOLOGICALs are not reported.

The badges are:

• Conchita: find a soup containing a phoenix.
• Gemini: discover a new twin bees shuttle variant.
• Gigamyriad: contribute 10¹³ objects.
• Hitchhiker: find a soup containing a Kok's galaxy.
• Limitless: observe a new natural infinite-growth pattern.
• Monarchist: discover a new queen bee shuttle variant.
• Sprotsmanship: contribute one third of a trillion objects to a different rule or symmetry.
• Trillionaire: contribute one trillion objects.
• Voyager: find one of the first twenty occurrences of a spaceship.

Soup-searching

Start by choosing the right version of apgsearch.

• If you want to look at non-totalistic rules, you'll need the hacked version of apgsearch 1.x.
• If your CPU is not x86_64 (all modern Intel/AMD CPUs are), or does not support at least SSE2 (most modern Intel/AMD CPUs do), you'll need apgsearch 1.x (regular or hacked).
  • You're not sure what your CPU can do? Take a look at /proc/cpuinfo on Linux, or use a tool like CPU-Z on Windows.
• If you do not have access to Unix-ish command line (Cygwin is fine), or you don't feel comfortable compiling C/C++ code, you'll need apgsearch 1.x (regular or hacked).
• If you want to look at outer-totalistic rules other than B3/S23, you'll need either apgsearch 1.x, apgmera 3.x. or apgluxe 4.x apgmera 3.x and apgluxe 4.x support SSE2 (slowest), AVX1 (slightly faster) or AVX2 (faster still), if your CPU supports these, and automatically detect which your CPU supports.
• If you want to search Generations or Larger than Life rules, you'll need apgluxe 4.x. (Note that since this requires a reasonably modern x86_64 CPU, you cannot currently search such rules if you don't have a sufficiently modern computer.)

apgnano 2.x is surpassed in every regard by apgmera 3.x and apgluxe 4.x; it should never be necessary to use it. apgmera 3.x may be faster than apgluxe 4.x, but

Soup-searching with apgsearch 1.x

You will need:

1. Golly
2. Python 2.7 (currently 2.7.13)
3. apgsearch 1.1.

If you want your contributions attributed to you, be sure to generate a Paoysha256 key (see above).

Install Golly and Python 2.7 if you haven't yet. Newer Python versions (3.x) will NOT work! Be sure to use a 32-bit Python if you're using a 32-bit Golly, and a 64-bit Python if you're using a 64-bit Golly. Also note that Python 2.7.11 is incompatible with Golly.

To install apgsearch, copy it into Golly's scripts/python directory. You may also want to edit the apgsearch script to default to using your Payosha256 key.

To search, simply start Golly and click on the script to run it.

Local logging is enabled by default; on Windows, you'll find logs in %APPDATA%\Golly\apgsearch\progress. On Linux/Unix-like systems, it's likely ~/.golly/apgsearch/progress (or something similar). Logs are named e.g. search_b1838fd357f0b003f985c20d19fd664a.txt.

If you want to search a different rule, it's recommended that you quit and restart Golly; this is due to Python scripts not releasing all their memory when they finish.

Soup-searching non-totalistic rules

You will need:

1. Golly and Python (as above)
2. A for awesome's hacked version of apgsearch (currently at version 0.54+0.31i)
3. If you're using a Golly version prior to 2.8, wildmyron's isotropic-rule.py.

Install everything the same way as above.

To search:

1. Choose a rule.
2. Run the hacked apgsearch by clicking on it; when prompted, enter the rule like this: "B3/S234c".

As with semi-totalistic rules, it is recommended that you quit and restart Golly if you want to search a different rule.

Soup-searching using apgnano 2.x

Consider using apgmera 3.x instead; it's faster and supports a wider variety of rules and symmetries.

If you must use apgnano 2.x, you will need:

1. A computer with an x86_64 CPU and a 64-bit OS.
2. A Unix-ish command line (Cygwin works if you're on Windows).
3. A C/C++ compiler and make tool.
4. apgnano 2.x (current version: 2.43).

If you're on Windows, install the 64-bit version (!) of Cygwin. Be sure to select the "gcc-g++" and "make" packages. Include their dependencies when asked to.

When running apgnano, supply the options you want. Note that unlike in apgsearch 1.x, local logging is DISABLED BY DEFAULT. Pass the "-L 1" command line parameter to enable it -- the "1" is mandatory. Logs are named e.g. log.1457867686.n_CAXK9hc99X6x.txt.

You may want to create a wrapper script to call apgnano with your desired options.

Soup-searching using apgmera 3.x

As above, but get apgmera 3.x instead of apgnano (current version: 3.28). Configure/compile like this, substituting your desired rule and symmetry:

$ python rule2asm.py b3678s34678 C1
$ make clean
$ make

The resulting binary will support SSE2, AVX1 and AVX2, and use the best instruction set your machine supports.

You must recompile the program each time you want to change the rule or symmetry; it may be advisable to keep different binaries on hand. The program also has the ability to recompile itself as well.

As with apgnano, when running apgmera, supply the options you want and note that local logging is DISABLED BY DEFAULT and must be enabled by passing "-L 1" on the command line; again, the "1" is mandatory. Logs are named e.g. log.1457882181.m_cDbsaQswZHeL.txt.

As above, you may want to create a wrapper script to call apgmera with your desired options.

Soup-searching using apgluxe 4.x

As above, but get apgluxe 4.x instead of apgnano (current version: 4.1). Configure/compile like this, substituting your desired rule and symmetry:

$ ./recompile.sh --rule b3s23 --symmetry C1

The recompilation script will automatically pull in the latest LifeLib version from Gitlab if necessary. The resulting binary will support SSE2, AVX1 and AVX2, and use the best instruction set your machine supports.

You must recompile the program each time you want to change the rule or symmetry; it may be advisable to keep different binaries on hand.

As with apgnano, when running apgluxe, supply the options you want and note that local logging is DISABLED BY DEFAULT and must be enabled by passing "-L 1" on the command line; again, the "1" is mandatory. Logs are named e.g. log.1457882181.m_cDbsaQswZHeL.txt.

As above, you may want to create a wrapper script to call apgmera with your desired options.

Caveats

The executive summary

So, to recap:

1. Run test hauls.
2. Mind Catagolue's haul requirements (size and number of soups/objects).
3. Be careful with rules combining high search speed and large hauls.
4. When in doubt, don't submit hauls too often to help keep hosting costs down.
5. Don't test client modifications on regular symmetries.
6. Don't break Catagolue.

Details

Catagolue imposes certain requirements on submitted hauls: they must contain at least 10,000 soups or 250,000 objects (or both); and they must not exceed a total size of 1 MiB.

In order to avoid running afoul of these limits, as well as to gauge the speed with which your rule of choice can be searched, try submitting a small test haul first: 10,000 soups works well for apgsearch 1.x, 1 million soups is a good choice for apgnano 2.x, apgmera 3.x and apgluxe 4.x. Take note of how long it takes to submit your test haul, and how big the resulting log is.

If your rule takes too long to search, try fewer soups. (If you're already at the server-imposed minimum of 10,000... tough luck.) If your test haul finished too quickly, try a bigger test. This'll also help you get a feel for how quickly hauls grow as you add soups.

You may find that with some rules (such as B/S012345678), even the smallest possible haul will exceed the 1 MiB limit. These rules are not soup-searchable, at least not on Catagolue; again, this is tough luck.

There are also some rules that combine fast searching and big hauls. Day & Night (B3678/S34678) is a notable example; a C1 haul of 8 million soups may take roughly 5 minutes (give or take a few, depending on how your computer's speed and CPU load) to finish using apgmera 3.28, and will weigh in at just under one megabyte. Keep in mind that hauls must be processed server-side, so when searching rules like these, don't run too many searcher instances at once. If Catagolue is struggling, e.g. by producing 500 Internal Server Errors or by failing to process all hauls submitted, cut down on the number of searchers. If you're already running just one, write a wrapper script to search something else (like Conway Life) in between hauls to give Catagolue time to cool down. This also applies if you're contributing to such a rule if another user is already submitting hauls for it.

The above also applies to other rules. Catagolue needs to carry out a datastore operation for each type of object in a haul, and datastore operations cost money. Thus, if you have the choice between submitting a haul of 200 distinct objects every 30 seconds, and submitting a haul of 1,000 distinct objects every 30 minutes, then absent a compelling reason to choose the former... choose the latter. You should not generally upload more than one haul every 20 minutes from a single machine.

A word on server-side haul processing: new hauls are commissioned to the census every 15 minutes. This process usually takes only a few minutes to finish; if it does not finish before the next commissioning process is started, 15 minutes later, it will be one of those days and Calcyman will not be happy.

All this said, most rules are fine to search and do not need any special considerations or attention.

= Testing client modifications

Modifications to the clients should be tested with a special "test" symmetry, rather than one of the "production" symmetries such as C1; by convention, all symmetries such symmetries should be suffixed "_Test" (case-insensitive).

Take care to disable haul verification if you're modifying the client, too, or your modified client may wrongly reject good hauls.

Support threads

• apgsearch v1.0 (discussion thread) at the ConwayLife.com forums

• Hacking apgsearch (discussion thread) at the ConwayLife.com forums

• apgsearch 2.2 (discussion thread) at the ConwayLife.com forums

• apgsearch 3.1 (discussion thread) at the ConwayLife.com forums

• apgsearch 4.0 (discussion thread) at the ConwayLife.com forums

External links

• Catagolue quota (discussion thread) at the ConwayLife.com forums