README.html

<h1>yass: Yet Another Soma Solver</h1>

<p><strong>yass</strong> is an open-source program for solving Piet Hein's Soma puzzle.</p>

<ul>
<li>Solves arbitrary Soma puzzle shapes</li>
<li>Finds all solutions, culling rotated/reflected duplicates (or optionally not)</li>
<li>Solves separated shapes, with individual part rotation/reflection culling</li>
<li>Supports pre-placement of Soma pieces (subset of all solutions)</li>
<li>Very fast performance: 0.024 seconds to solve the basic 3x3x3 cube shape, 0.0017 seconds/solve average on 4000+ example figures <a href="#footnote1"><sup>1</sup></a>, on mid-level hardware</li>
<li>Runtime performance tuning options</li>
<li>Text-based commandline executable with simple input file format, implemented as wrapper around independent C++ solver engine.</li>
</ul>

<h2>Contents <a name="contents"></a></h2>

<ul>
<li><a href="#license">License</a></li>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#purpose">Purpose</a></li>
<li><a href="#compiling">Compiling</a>

<ul>
<li><a href="#compilation_options">Compilation options</a></li>
<li><a href="#unittest">Unittest</a></li>
</ul></li>
<li><a href="#program_usage">Program usage</a>

<ul>
<li><a href="#basic_help">Basic help</a></li>
<li><a href="#extended_help">Extended help</a></li>
<li><a href="#tuning_options">Tuning options</a></li>
<li><a href="#std2yass_py">std2yass.py</a></li>
</ul></li>
<li><a href="#algorithms_and_implementation">Algorithms and implementation</a>

<ul>
<li><a href="#basic_algorithm">Basic algorithm</a></li>
<li><a href="#optimizations">Optimizations</a></li>
<li><a href="#implementation">Implementation</a></li>
</ul></li>
<li><a href="#autobio_soma_graphy">Autobio(soma)graphy</a></li>
<li><a href="#future_work">Future work</a></li>
<li><a href="#footnotes">Footnotes</a></li>
</ul>

<h2>License <a name="license"></a></h2>

<p>yass: Yet Another Soma Solver</p>

<p>Copyright (C) 2021 Mark R. Rubin</p>

<p>This file is part of yass.</p>

<p>The yass program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.</p>

<p>The yass program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.</p>

<p>You should have received a copy of the <a href="LICENSE.txt">GNU General Public License</a> along with the yass program. If not, see <a href="https://www.gnu.org/licenses/gpl.html">https://www.gnu.org/licenses/gpl.html</a></p>

<h2>Introduction <a name="introduction"></a></h2>

<p>The Soma Cube is arguably <a href="https://en.wikipedia.org/wiki/Piet_Hein_(scientist)">Piet Hein's</a> greatest invention, although his popularization of <a href="https://en.wikipedia.org/wiki/Superellipse">superellipses/superellipsoids</a>/<a href="https://en.wikipedia.org/wiki/Superegg">supereggs</a> and his <a href="https://en.wikipedia.org/wiki/Grook">&quot;grooks&quot;</a> (short poems) <a href="#footnote2"><sup>2</sup></a> are strong alternate contenders.</p>

<p>It's safe to assume that anyone reading this is already familiar with the Soma cube. In case not, there are many excellent online references including <a href="https://en.wikipedia.org/wiki/Soma_cube">Wikipedia</a>, and <a href="https://www.fam-bundgaard.dk/SOMA/SOMA.HTM">Thorlief's</a> excellent and extensive (if somewhat disjointed) website.</p>

<p>Better yet, make (<a href="https://www.instructables.com/Make-a-Wooden-Soma-Cube/">Instructables</a>, <a href="https://www.thingiverse.com/search?q=soma+cube&amp;type=things&amp;sort=relevant">Thingiverse</a>) or buy (Piet Hein's <a href="https://piethein.com/shop/183-games-amp-puzzles/217-soma-888-cm---wood-invented-1933/">posthumous website</a>, <a href="https://www.amazon.com/s?k=soma+cube&amp;i=toys-and-games">Amazon</a>) a Soma cube and experiment with it. Then come back to this software and compare your results.</p>

<h2>Purpose <a name="purpose"></a></h2>

<p><strong>yass</strong> was written for investigating interesting <a href="#footnote3"><sup>3</sup></a> details about Soma figures and their solutions. Things like:</p>

<ul>
<li><p>Is there a solution to a given shape? One of the joys of Soma is that in addition to the coincidence that Piet Hein originally set out to prove (can the seven Soma pieces in fact be assembled into a 3x3x3 cube?) there exist so many other impressionistic/evocative shapes, the vast majority of which <em>are</em> solvable. See several thousand examples at <a href="https://www.fam-bundgaard.dk/SOMA/FIGURES/ALLFIGS.HTM">Thorlief's</a> pages.</p></li>
<li><p>How many different solutions exist for a given figure? The program correctly finds the 240 unique solutions (11520 including rotations and reflections) for the basic 3x3x3 cube. The default output with rotations and reflections excluded greatly aids in understanding meaningful differences between the solutions.</p></li>
<li><p>Are there any solutions given restrictions on how one or more pieces are placed? For example, the program can be used as a brute-force demonstration of the elegant proof listed in <a href="https://en.wikipedia.org/wiki/Soma_cube#Solutions">Wikipedia</a> that all cube solutions must have the &quot;t&quot; piece spanning two corners of the cube (&quot;#&quot; characters in the output indicate an unsolvable figure):</p>

<pre><code>    $ ./soma figures/bad_t_face_cube.soma 
    ###
    ###
    ###

    ###
    ###
    ###

    #t#
    #tt
    #t#

    $ ./soma figures/bad_t_center_1_cube.soma 
    ###
    ###
    ###

    ###
    #t#
    ###

    #t#
    #t#
    #t#

    $ ./soma figures/bad_t_center_3_cube.soma
    ###
    #t#
    ###

    ###
    #tt
    ###

    ###
    #t#
    ###
</code></pre></li>
<li><p>Or alternately, a correctly pre-placed &quot;t&quot; piece yields the full count of 240 cube solutions, proving that such placement is mandatory without manually checking the complete output of <code>soma -a figures/cube.soma</code> (&quot;o&quot; characters indicate normal, non-pre-placed, shape cubicles -- see <a href="#extended_help">Extended help</a>, and input file format and piece naming <a href="#file_format_notes">notes</a>, below).</p>

<pre><code>    $ cat figures/good_t_cube.soma 
    ooo
    ooo
    ooo

    ooo
    ooo
    ooo

    ooo
    oto
    ttt

    $ ./soma -c figures/good_t_cube.soma
    figures/good_t_cube.soma: 240 solutions

    $ cat figures/cube.soma
    ooo
    ooo
    ooo

    ooo
    ooo
    ooo

    ooo
    ooo
    ooo

    $ ./soma -c figures/cube.soma
    figures/cube.soma: 240 solutions

    $ ./soma -a figures/cube.soma
    solution #1
    3zz
    zzc
    ttt

    33c
    ncc
    ptl

    nnl
    npl
    ppl

    ... solutions #2 through #239 ...

    solution #240
    ccl
    czl
    3ll

    czn
    tzp
    33p

    tzn
    tnn
    tpp
</code></pre></li>
<li><p>What about the disappointing <a href="#footnote4"><sup>4</sup></a> fact that not all interesting figures are solvable? For example, my own personal greatest disappointment, the &quot;windowed cube&quot;:</p>

<pre><code>    $ ./soma figures/internal_corner_hole_cube.soma 
    ### ..
    #.# ..
    ### ..

    ### ..
    #.. ..
    #.# #.

    ### ..
    ### #.
    ### ##
</code></pre></li>
<li><p>What interesting separated shapes can be combined into more basic ones (such as the basic cube)?</p>

<pre><code>    $ ./soma figures/disassemblable_cube.soma 
    ll. t..
    z.. ...
    ... ...

    zln tp.
    z.. tp.
    c.. ...

    zln tpp
    cnn 33.
    cc. 3..
</code></pre></li>
<li><p>And many other possibilities for for confirming or contradicting hypotheses formed while playing with Soma by hand.</p></li>
</ul>

<h2>Compiling <a name="compiling"></a></h2>

<p>The included source files (<code>./*.[ch]xx</code>) have been developed using GNU GCC (g++) version 7.5.0 with <code>-std=c++11</code>. Reports of incompatibilities with later releases or other compliant C++ compilers and/or pull requests with fixes for same are welcome <a href="#footnote5"><sup>5</sup></a>.</p>

<h4>Compilation options <a name="compilation_options"></a></h4>

<p>A <a href="Makefile"><code>Makefile</code></a> is provided. Commandline-overridable <code>make</code> variables allow easy setting of several compile-time switches controlling the implementation and features of the resulting executable. These include the following, although note that as per the runtime commandline <a href="#tuning_options">tuning options</a> below, the performance gains or losses resulting from changing them are usually minimal.</p>

<h5>Rotation</h5>

<p>Makefile or <code>make</code> commandline: <code>ROTATION=matrix</code> or <code>ROTATION=lambda</code>
<br>Source files: <code>#define SOMA_MATRIX_ROTATION</code> or <code>#define SOMA_LAMBDA_ROTATION</code>
<br>Default: <code>ROTATION=matrix</code> and <code>#define SOMA_MATRIX_ROTATION</code></p>

<p>An important part of the program's execution involves rotating and/or reflecting the 7 Soma pieces and/or entire Soma figures. Two alternate implementations are provided: One which multiplies X,Y,Z coordinates by 3x3 rotation matrices, and one which directly swaps the components using variable assignment statements. See e.g. <a href="rotators.cxx"><code>rotators.cxx</code></a> and the two versions of <code>static inline void rotate()</code> in <a href="piece.hxx">piece.hxx</a>.</p>

<p>It seems intuitively obvious that the <code>lambda</code> (swapping) version would be faster, but testing on typical modern CPUs shows the reverse, probably due to the massive hardware parallelism in such hardware. Again, the overall performance gain or loss between the two versions is very minimal.</p>

<h5>std::set</h5>

<p>Makefile or <code>make</code> commandline: <code>STD_SET=set</code> or <code>STD_SET=unordered</code>
<br>Source files: <code>#define SOMA_STD_SET_SET</code> or <code>#define SOMA_STD_SET_UNORDERED</code>
<br>Default: <code>STD_SET=unordered</code> and <code>#define SOMA_STD_SET_UNORDERED</code></p>

<p>Another important implementation detail is use of the STL (C++ Standard Template Library) &quot;set&quot; metaclasses for checking duplicate Soma solutions, among other things. A slight performance increase can be obtained by using <code>std::unordered_set</code> instead of <code>std:set</code>. Allowing the latter is included as it is more generally available than the former, although other parts of the code require C++11 or above which implies that <code>unordered_set</code> wil be present according to the C++ standards.</p>

<h5>stats</h5>

<p>Makefile or <code>make</code> commandline: <code>STATS=-D</code> or <code>STATS=-U</code>
<br>Source files: <code>#define SOMA_STATISTICS</code> or <code>#undef SOMA_STATISTICS</code>
<br>Default: <code>STATS=-U</code> and <code>#undef SOMA_STATISTICS</code></p>

<p>Defining <code>SOMA_STATISTICS</code> will conditionally compile tracking of interesting <a href="#footnote6"><sup>6</sup></a> statistics regarding the algorithm's execution on given Soma figures. It also enables the runtime commandline <code>-s</code> option to output the statistics. Due to the slight performance decrease caused by gathering the statistics (whether or not <code>-s</code> is specified), they are turned off by default.</p>

<h4>Unittest <a name="unittest"></a></h4>

<p>A unit test suite is provided, using example Soma shapes in the <a href="figures"><code>figures</code></a> subdirectory and corret results in the <a href="tests"><code>tests</code></a> directory. Execute <code>make test</code> to run the tests. A known incompatibility when using certain commandline options is handled via a text file containing the expected output.</p>

<h2>Program usage <a name="program_usage"></a></h2>

<p>Run the program with one of its two (basic and extended) help options.</p>

<h4>Basic help: <a name="basic_help"></a></h4>

<pre><code>    $ ./soma -h
    Solve SOMA figure(s).

    Usage: ./soma [OPTIONS] &lt;FILE&gt; [FILES...]

    FILE:       filename or &quot;-&quot; for standard input
    FILES:      additional files

    OPTIONS:
      -a            all solutions (only unique solutions by default)
      -r            include rotated and reflected solutions (forces -D 0)
      -c            only count of solutions, not solution(s) themselves
      -t            print elapsed time to solve figures
      -n            print filename before solution(s)
      -o &lt;FILE&gt;     output to file instead of standard output
      -O &lt;pieces&gt;   orphans check:     1 to 7 numbers, each 1 thru 7,
                                       or single 0 (default: 123456)
      -D &lt;pieces&gt;   duplicates checks: as per -O (default: 17)
      -S &lt;pieces&gt;   symmetry checks:   as per -O (default: 0)
      -P &lt;pieces&gt;   piece order:       7 characters, exactly one each of
                                       &quot;cpnztl3&quot; (default: ztcpnl3)
      -h            this help text
      -H            extended help
</code></pre>

<h4>Extended help: <a name="extended_help"></a></h4>

<pre><code>    $ ./soma -H
    Extended help.

    Usage: ./soma [OPTIONS] &lt;FILE&gt; [FILES...]

    OPTIONS (partial list, see &quot;-h&quot; for &quot;&lt;pieces&gt;&quot; syntax)
      -O &lt;pieces&gt;   orphans   check pieces (default: 123456)
      -D &lt;pieces&gt;   duplicate check pieces (default: 17)
      -S &lt;pieces&gt;   symmetry  check pieces (default: 0)
      -P &lt;pieces&gt;   piece order            (default: ztcpnl3)
      -h            basic help text (full list of options)
      -H            this extended help

    Orphan check (-O option):
      Program implements a recursive tree search, attempting to insert
      each SOMA piece in turn into SOMA figure. Pieces are numbered
      1 through 7, with insertion order specified by -P option.

      If piece number is in -O option, code checks for &quot;orphan&quot; cubicles
      after the piece is inserted. Orphan cubicles are single, or two
      orthogonally joined, cubicle(s) that are empty and not orthogonally
      joined to other empty cubicles.

      Checking consumes solving time but if successful prunes potentially
      large amounts of search tree space thus improving solution
      performance. Check is less likely to find orphans at earlier piece
      numbers but if successful prunes larger amount of search tree.
      Default values produce best results on large example set of SOMA
      figures. Checking at piece 7 is not useful because no orphans can
      exist after last piece. Set -O 0 to turn off all orphan checking.

    Duplicate check (-D option):
      During recursive tree search, program will check for duplicate
      solutions (rotated and/or mirrored) after each piece insertion if
      piece number is in -D &lt;pieces&gt;. Numbers/pieces as per orphan check,
      above. Setting -D 0 (or -r option) turns off all checking and
      reports all solutions.

      Checks at 1 through 6 are for each individual piece.
      Check at piece 7 is for entire figure including individually
      rotated/mirrored separated SOMA shapes. Missing solutions can
      result if neither piece 7, nor all of 1 through 6, are set.
      Additionally, setting 1-6 without 7 may result in missing solutions
      for separated shapes; the program forces -D 7 for such cases.

      Except for checking at piece #1, the computation time required for
      duplicate checking generally results in an overall increase in
      solution time.

    Symmetry check (-S option):
      During recursive tree search, program will check for symmetric SOMA
      shape cubicles before inserting each piece if piece number is in -S
      &lt;pieces&gt;. As per -D option, computation time required for symmetry
      checking (except at piece #1) generally results in an overall
      increase in solution time.

      Symmetry checking without duplicate checking (at the same piece
      number) is not sufficient for culling all duplicated
      rotated/mirrored solutions. Duplicate checking is efficient enough
      that despite the potentially large percentage of symmetric cubicles
      (4 non-symmetric out of 27 total for the basic 3x3x3 SOMA cube shape)
      overall performance gains are usually not significant. Note that
      symmetry checking of the &quot;p&quot;, &quot;n&quot;, &quot;z&quot;, or &quot;l&quot; pieces can produce
      specious results.

    Piece order (-P option):
      Order in which solver will attempt to place pieces into shape. Affects
      performance, but no universally-best order exists. In general &quot;easier&quot;
      pieces such as &quot;l&quot; and &quot;3&quot; should be at end of order. Pieces &quot;p&quot; and
      &quot;n&quot; must be contiguous, in that order, if -D option is enabled for
      either.

    File format:
      - Z slices of SOMA figure, separated by blank line(s)
      - Each slice: Y lines of X cubicles
      - SOMA shape defined by &quot;.&quot; or &quot; &quot; characters for empty space,
        any other character for shape cubicle
      - Characters &quot;c&quot;, &quot;p&quot;, &quot;n&quot;, &quot;z&quot;, &quot;t&quot;, &quot;l&quot;, &quot;3&quot; to pre-place piece(s)
      - &quot;#&quot; character to end of line is comment, ignored

      Example, SOMA &quot;battleship&quot; figure (indented here by 4 spaces, but
      will still solve correctly):

        # The classic battleship figure
        ....o....    # top Z slice
        .........    # second Y line of slice

        ...ooo...
        .........

        ..coooo..    # pre-place &quot;c&quot; piece
        .........

        occoooooo    # bottom Z slice
        oocoooooo    # with remaining &quot;c&quot; piece cubicles

      More info:
      - Orientation unimportant, suggest minimal Z slices, ordered top-to-bottom
      - Figures with multiple separated shapes accepted (useful for forcing
        specific solutions, and for additional removal of reflections/rotations)
      - Pre-placed pieces checked for correct number of cubicles (3 for &quot;3&quot; piece,
        4 for all others) but not for geometric shape (if wrong will produce
        incorrect solutions)
      - Tab characters not allowed except after &quot;#&quot; comment character
</code></pre>

<p><a name="file_format_notes"></a>
I realize this file format (much less the piece names) don't match what is likely <a href="https://www.fam-bundgaard.dk/SOMA/NOTATION.HTM">common practice</a>. See <a href="#std2yass_py">std2yass.py</a>, and particularly the <a href="#autobio_soma_graphy">Autobio(soma)graphy</a>, below. I've been writing Soma solver software for a very long time and it's too late to change now. It never occurred to me to call the pieces anything other than &quot;corner&quot;, &quot;positive&quot;, &quot;negative&quot;, &quot;zee&quot;, &quot;tee&quot;, &quot;ell&quot;, and &quot;three&quot;. I see the logic behind naming the last one &quot;vee&quot;, but basing that on a unique non-orthogonal rotation is too incongruous. Similarly, the &quot;slice&quot; file format seems as intuitively obvious now as it did decades ago when I first implemented it.</p>

<h5>Tuning options <a name="tuning_options"></a></h5>

<p>Note that the performance tuning options (<code>-O</code>, <code>-D</code>, <code>-S</code>, and <code>-P</code>, <a href="#extended_help">above</a>) are included mainly for completeness and experimentation. The default values perform perfectly adequately in almost all cases, and the program is more than fast enough for any conceivable interactive use with all but the most pathological of settings.</p>

<h3><code>std2yass.py</code> <a name="std2yass_py"></a></h3>

<p>Additionally, a small Python script (<a href="std2yass.py"><code>std2yass.py</code></a>) is included for converting <a href="https://www.fam-bundgaard.dk/SOMA/NOTATION.HTM">&quot;standard&quot;</a> figure notation to the file format used by yass.</p>

<pre><code>    $ ./std2yass.py -h 
    usage: std2yass.py [-h] [infile] [outfile]

    positional arguments:
      infile
      outfile

    optional arguments:
      -h, --help  show this help message and exit

    $ cat snake.std
    /22......../.2......../.244....../.446......
    /........../........../...665..../...655....
    /........../........../.....537../.....333..
    /........../........../.......771/.......711

    $ ./std2yass.py snake.std
    oo........
    ..........
    ..........
    ..........

    .o........
    ..........
    ..........
    ..........

    .ooo......
    ...ooo....
    .....ooo..
    .......ooo

    .ooo......
    ...ooo....
    .....ooo..
    .......ooo

    $ ./std2yass.py snake.std | ./soma -    
    ll........
    ..........
    ..........
    ..........

    .l........
    ..........
    ..........
    ..........

    .lzz......
    ...ppn....
    .....ntc..
    .......cc3

    .zzp......
    ...pnn....
    .....ttt..
    .......c33
</code></pre>

<h2>Algorithms and implementation <a name="algorithms_and_implementation"></a></h2>

<h3>Basic algorithm <a name="basic_algorithm"></a></h3>

<p>The software is based on a simple recursive tree descent algorithm. Each Soma piece in turn is tested against all currently empty cube positions in the shape to be solved. This is done by aligning one pre-chosen cube of the piece with each empty shape position, and then orthogonally rotating the piece into each of its unique orientations. If all the remaining piece cubes (2 for the &quot;3&quot; piece, 3 for all others) are inside the shape and not conflicting with any previously placed piece, the algorithm proceeds to the next piece. If not, it backtracks to the previous piece and tries its next rotation and/or position in the shape.</p>

<p>When the last piece has been placed, a solution has been found. If all solutions have been requested (<code>-a</code> or <code>-c</code> option, see <a href="#program_usage">above</a>) the code tries another orientation of the last piece and/or backtracks as previously described. Solving halts when backtracking returns to the first piece and it cannot be placed.</p>

<h3>Optimizations <a name="optimizations"></a></h3>

<p>See runtime documentation for <code>-O</code>, <code>-D</code>, <code>-S</code>, and <code>-P</code> options in <a href="#extended_help">Extended help</a>, above.</p>

<p>The experimentally-derived &quot;optimal&quot; default settings for these options are counter-intuitive. &quot;Big O&quot; analysis would indicate that pruning large amounts of the solution search tree space would result in faster solution times, but the computational cost of doing the checks generally results in the opposite, except in specific cases such as doing symmetry and duplicate checking after the first piece (where pruning has the greatest impact and there is a higher chance of successful checks).</p>

<p>The code has other, always turned on, optimizations. These include:</p>

<ul>
<li>Pre-computation of unique piece rotations/orientations. Each piece can be rotated to 24 different orientations (the original Z axis rotated to the positive or negative X, Y, and Z axes and then 4 rotations around each), but given piece symmetries only the following are unique:

<pre><code>c:  8 orientations
p: 24 orientations
n: 24 orientations
z: 12 orientations
t: 12 orientations
l: 24 orientations
3: 12 orientations
</code></pre></li>
</ul>

<p><a name="cull_impossible"></a></p>

<ul>
<li><p>Prior to the executing the recursive descent algorithm the above piece orientations are further culled on a per shape cubicle basis. If a piece cannot be placed in a given position and orientation with no other pieces present there is no point in repeatedly checking that position+orientation during the recursive search.</p></li>
<li><p>Also per-shape, a fairly large number of data structures are generated to optimize performance. For example, arrays of neighboring shape cubicles populated to avoid linear (through the 27 shape cubicles) or geometric (via X,Y,Z coordinate offsets) searches.</p></li>
</ul>

<h3>Implementation <a name="implementation"></a></h3>

<p>The algorithms are implemented in code as a text-based commandline wrapper (<a href="main.cxx"><code>main.cxx</code></a>) around a C++ engine (<code>class Soma</code> in files <a href="soma.cxx"><code>soma.cxx</code></a> and <a href="soma.hxx"><code>soma.hxx</code></a>) and associated classes in the remaining <code>*.[ch]xx</code> files.</p>

<p>The code is extensively documented but will likely fail code quality analysis tools which check the ratio of comments to total source lines (832 to 4472 at a recent count). It is the author's opinion that code itself describes what it does (if well-written, including descriptive names for variables, methods, classes, etc.), while comments should explain <em>why</em> it does it what it does (background explanations and justifications). The code here is therefore notably lacking in such comments as:</p>

<pre><code>    // loop through all the elements in the container
    for (element : container) {
</code></pre>

<p>and <a href="#footnote7"><sup>7</sup></a>:</p>

<pre><code>    ++counter;  // increment counter by one
</code></pre>

<p>In general, each class's public methods are documented at their declarations in <code>classname.hxx</code> files, and private methods at their definitions in <code>classname.cxx</code> files.</p>

<p>Example code for using <code>class Soma</code> via its <code>Soma::shape</code> (input) and <code>Soma::solution</code> (output) API instead of the text- and file-based <code>Soma::read</code> and <code>Soma::print</code> methods can be found in the <code>read_pieces_file</code> and <code>print_api</code> functions in file <a href="main.cxx"><code>main.cxx</code></a>.</p>

<p>A possible reason why doing duplicate checking only after the last piece has been placed (see <a href="#optimizations">Optimizations</a>, above) is faster than doing it for each piece is that the checking implementation, despite being inherently <em>O(n<sup>2</sup>)</em>, is very efficient. Each solution is checked against known solutions stored in an <code>std::unordered_set</code> (optionally <code>std::set</code>) via fast <code>Signature::operator==</code> or <code>Signature::operator&lt;</code> methods which merely compare two pairs of packed 64-bit integers. If the solution is new, all of its possible rotations and reflections are immediately generated and added to the set of known solutions. In this way the rotating/reflecting is done only once per unique solution (240 times for the basic 3x3x3 cube shape) instead of every time time a new, unknown solution is found (11520 times).</p>

<h2>Autobio(soma)graphy <a name="autobio_soma_graphy"></a></h2>

<p>I have a very long personal history with the Soma cube.</p>

<p>My father made two wooden Soma cubes, I assume inspired by and sometime after they were described in Martin Gardner's &quot;Mathematical Games&quot; column in the September 1958 issue of <em>Scientific American</em> magazine. I would have been far too young at the time to have been aware of the exact date -- my earliest memories are that the cubes were &quot;always around&quot; in my childhood.</p>

<p>I still have one of the two, the other having disappeared sometime after I left the family home. My father was a master craftsman, and despite not owning woodworking machinery such as table saws, jointers, and planers, instead using only hand saws and planes, the ones he made were more precise than most of the mass-produced wooden and plastic ones I purchased years later. Lack of parallelism, perpendicularity, and/or dimensional accuracy in a Soma cube impacts the tactile joy of playing with one as the pieces don't fit together well and solved figures show gaps and don't support themselves. Magnetic cubes alleviate some of these problems (see below).</p>

<p>I wrote my first Soma solver software in my teens, sometime around 1970. It ran on a mainframe computer which filled half of a basketball court sized room. I think the final version was written in assembly language although there may have been precursors in Fortran and/or Basic. It implemented the same simple recursive descent algorithm which is the basis of this repository's code, but without any of its rotation/reflection culling. I deeply mourn the fact that the code no longer exists, the punch cards and/or paper tape containing the source and executable having long since been lost.</p>

<p>Approximately every 10 years one thing or another seems to bring me back to Soma. I'll come across a new cube for sale and/or throw together some code for a few weeks and then move on to other pursuits. (There are limits to recreational mathematics fetishism, even mine.) Sometime in the 1980's I found a wooden version for sale in a store, and similarly, in the 1990's the rather poorly made plastic &quot;Block By Block&quot; offering by the Binary Arts company.</p>

<p>In 1996 I was inspired to recreate my long lost mainframe code, largely as an excuse to see how well GCC would compile an object-oriented implementation of the algorithm. For some forgotten reason (likely another new cube purchase) I wanted to look at some Soma solutions in 2010, and as the old executable no longer linked with the then-current Linux shared libraries, I rewrote the code, updating the deprecated and rather strange <code>iostream</code> API from the pre-standardized 1996 <code>g++</code> libraries.</p>

<p>Finally, this current version began when I resurrected a broken 3D printer that had been given to me several years earlier and realized I could finally make a Soma cube to my desired standards. (I'm not quite the craftsman my father was, and I don't have access to the kind of metal- and/or woodworking machinery my lack of skill requires me to have in order to achieve precise results.)</p>

<p>Before using the printer, I checked online for currently available commercial cubes, and found magnetic cubes being offered for sale. I was instantly puzzled: How could a Soma cube be magnetized? Any cube face of any piece can be arbitrarily placed against any other, so regardless of how the magnets are arranged it's highly likely that in at least some cases two north or two south poles will be facing each other and repel the pieces instead of holding them together. An analogous problem exists if magnets and ferromagnetic plates are used instead (two magnets will repel, and two plates won't attract, each other).</p>

<p>Another 30 seconds of pondering produced the answer, although my solution is slightly different (in details, not concept) than that in the commercial products. I'll leave the answer to the reader's own thoughts and/or research. I did buy a magnetic cube to confirm my suppositions and to have one to play with while making my own.</p>

<p>As an aside, the Soma cube's younger, better known cousin, the Rubik's Cube, is trivial to magnetize. The inner faces of the 20 movable &quot;cubies&quot; and the 6 rotatable face pseudo-cubies always touch others of a single type. Corner and edge cubies' faces always touch each other, and edge cubies touch face pseudo-cubies, so installing magnets north pole outwards on the corners and faces and south on the edges (or vice-versa) works.</p>

<p>I find it very satisfying that magnetizing a Soma cube adds a mechanical component to the intrinsically mathematical puzzle. As Douglas Hofstadter pointed out in his &quot;Metamagical Themas&quot; column (the successor to Martin Gardner's &quot;Mathematical Games&quot; series) in the March 1981 <em>Scientific American</em> magazine, in addition to the problem of solving one it is not obvious how a Rubik's cube is mechanically held together in the first place. (Ironically, he stated that most people initially guess that magnets are used.) As another aside, I claim to have one of if not the first Rubik's cube ever sold in the USA. Along with many others I was smitten by the CGI rendering on the Scientific American cover and Hofstadter's article inside. A friend and I called our local &quot;Toys 'R' Us&quot; store every day for several weeks asking if they had them for sale, always getting the response, &quot;Rubik's <em>what</em>? No, I told you I don't know what that is. Stop calling here!&quot; until one day: &quot;You again, I told you ... wait a second ... hey, Manny! What was that we got in this morning's delivery? Something 'Cube'? OK ... yeah, we got them, whatever they are.&quot;</p>

<p>We immediate ran over and bought two apiece. I scrambled one and then painstakingly spent three weeks developing &quot;operators&quot; on the other, being careful to write down and reverse my steps so I could restore it to its solved state where seeing what was going on was easier. (I only failed once and had to resort to disassembling the cube and putting it back together.) I finally worked out a small set of operators sufficient for a full solution, and eventually got solving down to approximately two minutes which was fast for that era before widely available, efficient algorithms were published. At that point I lost interest, realizing that to get any better would require significant effort and practice, and as with card-counting blackjack in Las Vegas, any potential rewards weren't worth the trouble.</p>

<p>Back to Soma cubes ... in my opinion, magnets take them to the next level. They make solving figures much easier as the pieces hold together without balancing or using a flat surface, and some figures that aren't free standing without them become so with. Plus, there's something tactically and audibly satisfying about hearing and feeling the magnets flip and click together (there's a hint about the mechanical design). They've sparked this decade's interest in Soma for me.</p>

<p>I finally decided to add rotation and reflection culling to the code (which I'd wanted to do for years), along with several other features such as implementing the same for separated figures. I find it very interesting to have an accurate count of unique solutions after estimating the number when solving by hand. Also having indisputable confirmation that a figure is unsolvable after coming to that conclusion (but with nagging doubts) experimentally/intellectually.</p>

<p>This open-source repository is the end result. If others find it interesting and/or useful that's an additional benefit.</p>

<h2>Future work <a name="future_work"></a></h2>

<p>All somewhat good things must come to an end, and it is time to wrap up development on this code for now.</p>

<p>A possible alternate implementation could entail placing and orienting the &quot;p&quot;, &quot;n&quot;, &quot;z&quot;, and &quot;l&quot; pieces by pairs of orthogonally-connected shape cubicles instead of by single ones. (The &quot;c&quot;, &quot;t&quot;, and &quot;3&quot; pieces would be handled as they are now.) This would aid in symmetry searches which are currently hampered by the fact that <code>Shape::set_statuses</code> chooses an arbitrary cubicle from the set of symmetric ones, and that may or may not match the pre-chosen &quot;central&quot; cubicle of the pieces. See <code>-S</code> documentation in <a href="#extended_help">Extended help</a>, above. A pathological example case is <a href="figures/pieces.soma"><code>figures/pieces.soma</code></a> (simply the pieces themselves, separated) where choosing the wrong cubicle can result in the code not being able to place the piece in its obvious, unique position.</p>

<p>In some ways this would be an optimization. For example, the &quot;l&quot; piece, instead of having 24 unique orientations around its current single, central cube would have only 8 around its pair of two central cubes. But, depending on the Soma shape, the number of cubicle pairs to test for piece insertion would be larger. For the basic 3x3x3 cube shape this would go from 27 single cubicles to 108 pairs of cubicles. it would likely be less for other shapes, so the cube shape's overall loss (1/3 the orientations but 4 times the placements) might be an edge case. And culling of impossible positions/orientations (see <a href="#cull_impossible">above</a>) further changes the equation.</p>

<p>If someone would like to try this approach (of course while respecting the <a href="#license">License</a>) I'd be interested in the results.</p>

<h2>Footnotes <a name="footnotes"></a></h2>

<ol>
<li><a name="footnote1"></a> <a href="https://www.fam-bundgaard.dk/SOMA/FIGURES/FIGURES.HTM">SOMA Figures</a> at &quot;Thorlief's SOMA Page&quot;</li>
<li><a name="footnote2"></a> In particular: &quot;Problems worthy of attack. Prove their worth by fighting back.&quot;</li>
<li><a name="footnote3"></a> Interesting to a complete Soma cube nerd like me.</li>
<li><a name="footnote4"></a> Or alternately the Zen-like meta-perfection that not everything in the world of Soma shapes is achievable.</li>
<li><a name="footnote5"></a> Reports about non-compliant compilers or those with proprietary extensions not so much.</li>
<li><a name="footnote6"></a> Interesting to a complete optimization nerd like me.</li>
<li><a name="footnote7"></a> My favorite straw-man example.</li>
</ol>