commit d65ce8e86b517ef3f7d48cf5ded1101444e05b2b
parent bc2e6b8a8d5a6eccd2c2ac433e8a307ee356f14e
Author: Sebastiano Tronto <sebastiano@tronto.net>
Date: Tue, 31 Oct 2023 19:17:42 +0100
Reorganized documentation
Diffstat:
7 files changed, 178 insertions(+), 177 deletions(-)
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
# Prototype for a new optimal solver
-Work in progress.
+Work in progress. There is some documentation at the bottom of this page,
+but do not believe it. Everything is in a state of flux and can change
+without notice.
## Running tests
@@ -38,9 +40,8 @@ $ make test
### Documentation and interface
-* remove the constant #define's from cube.h (write a comment instead)
-* reconsider content of cube.h, remove some stuff
-* remove doc folder, inline documentation as comments in cube.h or cube.c
+* inline some documentation as comments in cube.h or cube.c
+* README.md (maybe convert to txt?) becomes the reference documentation
### AVX2
@@ -64,3 +65,101 @@ $ make test
[_mm256_shuffle_epi8](https://www.intel.com/content/www/us/en/docs/cpp-compiler/developer-guide-reference/2021-10/mm256-shuffle-epi8.html))
* Inspect compiled assembly
* Use valgrind tool cachegrind and other profiling tools
+
+
+## Internal representation of the cube
+
+The plan (TODO) is to have multiple implementations: some that
+take advantage of advanced CPU instructions (SIMD) and a fallback
+"array" representation that works on any architecture.
+
+### Array representation (fallback)
+
+In this implementation of the cube.h interface, the cube is represented
+by two arrays of 8-bit unsigned integers, one for centers and one for
+corners. The 4 leas-significant digits of each bit determine the piece,
+the other 4 are used for orientation or kept to 0.
+
+Edges:
+ xxxopppp (x = unused, o = orientation, p = piece)
+
+Corners:
+ xooxpppp (x = unused, o = orientation, p = piece)
+
+The two bits for CO are shifted to make it possible to perform mod 3
+operations (sum, inverse) using only addition and bitwise operators.
+See below for details.
+
+The third bit is needed because x+y+1 can exceed 4.
+
+### AVX2
+
+Work in progress
+
+
+## Textual representation of the cube
+
+The functions readcube() and writecube() use different formats to read
+and write a cube to text. Not all formats are supported for both input
+and output.
+
+### H48 - standard format for h48 (read, write)
+
+Each edge is represented by two letters denoting the sides it belongs to
+and one number denoting its orientation (0 oriented, 1 mis-oriented).
+Similarly, each corner is represented by three letters and a number
+(0 oriented, 1 twisted clockwise, 2 twisted counter-clockwise).
+Edge orientation is relative to the F / B axis, corner orientation is
+relative to the U / D axis.
+
+The pieces are ordered such that the solved cube looks like this:
+
+UF0 UB0 DB0 DF0 UR0 UL0 DL0 DR0 FR0 FL0 BL0 BR0
+UFR0 UBL0 DFL0 DBR0 UFL0 UBR0 DFR0 DBL0
+
+Whitespace (including newlines) between pieces is ignored when reading
+the cube, and a single whitespace character is added between pieces
+when writing.
+
+The cube after the moves R'U'F looks like this:
+
+FL1 BR0 DB0 UR1 UF0 UB0 DL0 FR0 UL1 DF1 BL0 DR0
+UBL1 DBR1 UFR2 DFR2 DFL2 UBL2 UFL2 DBL0
+
+### SRC - representation of the object in C code for cube_array (write)
+
+The exact format depends on the internal cube representation (TODO: actually
+this is false, because I need all formats for code generation; also adapating
+tests is hard). It is guaranteed that, if OUT is the output in this format,
+the line
+
+cube_t cube = OUT;
+
+is interpreted correctly by h48.
+
+
+## Transformations
+
+Transformations can be either simple rotations or a rotation composed
+with a mirroring.
+
+Simple rotations are denoted by two letters corresponding to the faces
+to be moved to the U and F positions, respectively. For example FD is
+the rotation that brings the F face on top and the D face on front.
+
+A composed rotation + mirror is obtained by applying the corresponding
+rotation to the solved cube mirrored along the M plane.
+
+For example, to apply the transformation RBm (mirrored RB) to a cube C:
+ 1a. Apply a mirror along the M plane to the solved cube
+ 1b. Rotate the mirrored cube with z' y2
+ 3. Apply the cube C to the transformed solved cube
+ 4. Apply the transformations of step 1a and 1b in reverse
+
+The orientation of pieces after a rotation ignores the new position
+of centers. A rotated cube can technically be inconsistent, because
+the parity of the edge permutation has to be adjusted considering the
+parity of the centers, which we ignore.
+
+The utility script mirror.sh transforms a solved, rotated cube to its
+mirrored and rotated version.
diff --git a/doc/CUBE_INTERNAL.md b/doc/CUBE_INTERNAL.md
@@ -1,24 +0,0 @@
-# Internal representation of the cube
-
-The plan (TODO) is to have multiple implementations: some that
-take advantage of advanced CPU instructions (SIMD) and a fallback
-"array" representation that works on any architecture.
-
-# Array representation (fallback)
-
-In this implementation of the cube.h interface, the cube is represented
-by two arrays of 8-bit unsigned integers, one for centers and one for
-corners. The 4 leas-significant digits of each bit determine the piece,
-the other 4 are used for orientation or kept to 0.
-
-Edges:
- xxxopppp (x = unused, o = orientation, p = piece)
-
-Corners:
- xooxpppp (x = unused, o = orientation, p = piece)
-
-The two bits for CO are shifted to make it possible to perform mod 3
-operations (sum, inverse) using only addition and bitwise operators.
-See below for details.
-
-The third bit is needed because x+y+1 can exceed 4.
diff --git a/doc/CUBE_TEXT.md b/doc/CUBE_TEXT.md
@@ -1,37 +0,0 @@
-# Textual representation of the cube
-
-The functions readcube() and writecube() use different formats to read
-and write a cube to text. Not all formats are supported for both input
-and output.
-
-## H48 - standard format for h48 (read, write)
-
-Each edge is represented by two letters denoting the sides it belongs to
-and one number denoting its orientation (0 oriented, 1 mis-oriented).
-Similarly, each corner is represented by three letters and a number
-(0 oriented, 1 twisted clockwise, 2 twisted counter-clockwise).
-Edge orientation is relative to the F / B axis, corner orientation is
-relative to the U / D axis.
-
-The pieces are ordered such that the solved cube looks like this:
-
-UF0 UB0 DB0 DF0 UR0 UL0 DL0 DR0 FR0 FL0 BL0 BR0
-UFR0 UBL0 DFL0 DBR0 UFL0 UBR0 DFR0 DBL0
-
-Whitespace (including newlines) between pieces is ignored when reading
-the cube, and a single whitespace character is added between pieces
-when writing.
-
-The cube after the moves R'U'F looks like this:
-
-FL1 BR0 DB0 UR1 UF0 UB0 DL0 FR0 UL1 DF1 BL0 DR0
-UBL1 DBR1 UFR2 DFR2 DFL2 UBL2 UFL2 DBL0
-
-## SRC - representation of the object in C code for cube_array (write)
-
-The exact format depends on the internal cube representation. It is
-guaranteed that, if OUT is the output in this format, the line
-
-cube_t cube = OUT;
-
-is interpreted correctly by h48.
diff --git a/doc/TRANSFORMATIONS.md b/doc/TRANSFORMATIONS.md
@@ -1,23 +0,0 @@
-Transformations can be either simple rotations or a rotation composed
-with a mirroring.
-
-Simple rotations are denoted by two letters corresponding to the faces
-to be moved to the U and F positions, respectively. For example FD is
-the rotation that brings the F face on top and the D face on front.
-
-A composed rotation + mirror is obtained by applying the corresponding
-rotation to the solved cube mirrored along the M plane.
-
-For example, to apply the transformation RBm (mirrored RB) to a cube C:
- 1a. Apply a mirror along the M plane to the solved cube
- 1b. Rotate the mirrored cube with z' y2
- 3. Apply the cube C to the transformed solved cube
- 4. Apply the transformations of step 1a and 1b in reverse
-
-The orientation of pieces after a rotation ignores the new position
-of centers. A rotated cube can technically be inconsistent, because
-the parity of the edge permutation has to be adjusted considering the
-parity of the centers, which we ignore.
-
-The utility script mirror.sh transforms a solved, rotated cube to its
-mirrored and rotated version.
diff --git a/src/_constants.c b/src/_constants.c
@@ -1,3 +1,75 @@
+#define U 0U
+#define U2 1U
+#define U3 2U
+#define D 3U
+#define D2 4U
+#define D3 5U
+#define R 6U
+#define R2 7U
+#define R3 8U
+#define L 9U
+#define L2 10U
+#define L3 11U
+#define F 12U
+#define F2 13U
+#define F3 14U
+#define B 15U
+#define B2 16U
+#define B3 17U
+
+#define UFr 0
+#define ULr 1
+#define UBr 2
+#define URr 3
+#define DFr 4
+#define DLr 5
+#define DBr 6
+#define DRr 7
+#define RUr 8
+#define RFr 9
+#define RDr 10
+#define RBr 11
+#define LUr 12
+#define LFr 13
+#define LDr 14
+#define LBr 15
+#define FUr 16
+#define FRr 17
+#define FDr 18
+#define FLr 19
+#define BUr 20
+#define BRr 21
+#define BDr 22
+#define BLr 23
+
+#define UFm 24
+#define ULm 25
+#define UBm 26
+#define URm 27
+#define DFm 28
+#define DLm 29
+#define DBm 30
+#define DRm 31
+#define RUm 32
+#define RFm 33
+#define RDm 34
+#define RBm 35
+#define LUm 36
+#define LFm 37
+#define LDm 38
+#define LBm 39
+#define FUm 40
+#define FRm 41
+#define FDm 42
+#define FLm 43
+#define BUm 44
+#define BRm 45
+#define BDm 46
+#define BLm 47
+
+#define errormove 99U
+#define errortrans 99U
+
#define _c_ufr 0U
#define _c_ubl 1U
#define _c_dfl 2U
diff --git a/src/cube.h b/src/cube.h
@@ -1,6 +1,3 @@
-/* Types *********************************************************************/
-
-/* See doc/CUBE_INTERNAL.md for a description of the cube format */
typedef struct {
uint8_t c[16];
uint8_t e[16];
@@ -14,8 +11,6 @@ typedef cube_arr_t cube_t;
typedef uint8_t move_t;
typedef uint8_t trans_t;
-/* Functions *****************************************************************/
-
int readmoves(char *, move_t *);
void writemoves(move_t *, int, char *);
trans_t readtrans(char *);
@@ -24,11 +19,9 @@ void writetrans(trans_t, char *);
move_t inverse_move(move_t);
trans_t inverse_trans(trans_t);
-/* Not all formats are supported for both read and write. */
-/* See doc/CUBE_TEXT.md for details. */
typedef enum {H48, SRC} format_t;
-cube_t readcube(format_t, char *);
-void writecube(format_t, cube_t, char *);
+cube_t readcube(format_t, char *); /* Supports: H48 */
+void writecube(format_t, cube_t, char *); /* Supports: H48, SRC */
cube_t solvedcube(void);
cube_t zerocube(void);
@@ -41,82 +34,3 @@ cube_t move(cube_t, move_t);
cube_t inverse(cube_t);
cube_t compose(cube_t, cube_t);
cube_t transform(cube_t, trans_t);
-
-/* Constants for moves and transformations ***********************************/
-
-/* Standard moves */
-#define U 0U
-#define U2 1U
-#define U3 2U
-#define D 3U
-#define D2 4U
-#define D3 5U
-#define R 6U
-#define R2 7U
-#define R3 8U
-#define L 9U
-#define L2 10U
-#define L3 11U
-#define F 12U
-#define F2 13U
-#define F3 14U
-#define B 15U
-#define B2 16U
-#define B3 17U
-
-/* Regular transformations (rotations) */
-#define UFr 0
-#define ULr 1
-#define UBr 2
-#define URr 3
-#define DFr 4
-#define DLr 5
-#define DBr 6
-#define DRr 7
-#define RUr 8
-#define RFr 9
-#define RDr 10
-#define RBr 11
-#define LUr 12
-#define LFr 13
-#define LDr 14
-#define LBr 15
-#define FUr 16
-#define FRr 17
-#define FDr 18
-#define FLr 19
-#define BUr 20
-#define BRr 21
-#define BDr 22
-#define BLr 23
-
-/* Mirrored transformations */
-#define UFm 24
-#define ULm 25
-#define UBm 26
-#define URm 27
-#define DFm 28
-#define DLm 29
-#define DBm 30
-#define DRm 31
-#define RUm 32
-#define RFm 33
-#define RDm 34
-#define RBm 35
-#define LUm 36
-#define LFm 37
-#define LDm 38
-#define LBm 39
-#define FUm 40
-#define FRm 41
-#define FDm 42
-#define FLm 43
-#define BUm 44
-#define BRm 45
-#define BDm 46
-#define BLm 47
-
-/* Errors */
-#define errormove 99U
-#define errortrans 99U
-
diff --git a/test/050_transform/transform_tests.c b/test/050_transform/transform_tests.c
@@ -14,7 +14,7 @@ int main() {
fgets(str, STRLENMAX, stdin);
t = readtrans(str);
- if (t == errortrans) {
+ if (t >= 48) {
printf("Error reading trans\n");
return 1;
}
