From 8b72e391c7185e3da0dfbf0ab60068ac37e4d5cc Mon Sep 17 00:00:00 2001 From: Sebastiano Tronto Date: Tue, 22 Apr 2025 09:00:15 +0200 Subject: Removed old scripts and updated public API --- src/nissy.h | 98 +++++++++++++++++++------------------------------------------ 1 file changed, 30 insertions(+), 68 deletions(-) (limited to 'src/nissy.h') diff --git a/src/nissy.h b/src/nissy.h index a5b3015..963571f 100644 --- a/src/nissy.h +++ b/src/nissy.h @@ -5,12 +5,11 @@ All the functions return 0 or a positive integer in case of success and a negative integer in case of error, unless otherwise specified. See at the bottom of this file for the list of error codes and their meaning. -All cube arguments are in B32 formats, unless otherwise specified. -Other available formats are H48 and SRC. See README.md for more info on -these formats. +TODO: explain cube format Accepted moves are U, D, R, L, F and B, optionally followed by a 2, a ' or a 3. +TODO update when we accept also wide moves, slices and rotations A transformation must be given in the format (rotation|mirrored) (2 letters) @@ -21,9 +20,7 @@ for example 'rotation UF' or 'mirrored BL'. /* Constants *****************************************************************/ /* Some constants for size for I/O buffers */ -#define NISSY_SIZE_B32 22U -#define NISSY_SIZE_H48 88U -#define NISSY_SIZE_CUBE_MAX NISSY_SIZE_H48 +#define NISSY_SIZE_CUBE 24U #define NISSY_SIZE_TRANSFORMATION 12U #define NISSY_SIZE_SOLVE_STATS 10U #define NISSY_SIZE_DATAID 255U @@ -37,8 +34,8 @@ for example 'rotation UF' or 'mirrored BL'. #define NISSY_NISSFLAG_ALL \ (NISSY_NISSFLAG_NORMAL | NISSY_NISSFLAG_INVERSE | NISSY_NISSFLAG_MIXED) -/* The solved cube in B32 format */ -#define NISSY_SOLVED_CUBE "ABCDEFGH=ABCDEFGHIJKL" +/* The solved cube */ +#define NISSY_SOLVED_CUBE "ABCDEFGH=ABCDEFGHIJKL=A" /* Error codes ***************************************************************/ @@ -58,8 +55,7 @@ provided an unsolvable cube as input. /* The value NISSY_ERROR_INVALID_CUBE means that the provided cube is -invalid. It could be written in an unknown format, or in a format -different from what specified, or simply ill-formed. +invalid. It could be written in an unknown format, or be ill-formed. */ #define NISSY_ERROR_INVALID_CUBE -10LL @@ -84,12 +80,6 @@ is invalid. */ #define NISSY_ERROR_INVALID_TRANS -30LL -/* -The value NISSY_ERROR_INVALID_FORMAT means that the given format is -not known. -*/ -#define NISSY_ERROR_INVALID_FORMAT -40LL - /* The value NISSY_ERROR_INVALID_SOLVER means that the given solver is not known. @@ -139,10 +129,10 @@ of this kind to sebastiano@tronto.net. Thanks! Apply the secod argument as a permutation on the first argument. Parameters: - cube - The first cube, in B32 format. - permutation - The second cube, in B32 format. This cube is treated as a - permutation and "applied" to the first cube. - result - The return parameter for the resulting cube, in B32 format. + cube - The first cube. + permutation - The second cub. This cube is treated as a permutation and + "applied" to the first cube. + result - The return parameter for the resulting cube. Return values: NISSY_OK - The cubes were composed succesfully. @@ -155,17 +145,17 @@ Return values: */ long long nissy_compose( - const char cube[static NISSY_SIZE_B32], - const char permutation[static NISSY_SIZE_B32], - char result[static NISSY_SIZE_B32] + const char cube[static NISSY_SIZE_CUBE], + const char permutation[static NISSY_SIZE_CUBE], + char result[static NISSY_SIZE_CUBE] ); /* Compute the inverse of the given cube. Parameters: - cube - The cube to be inverted, in B32 format. - result - The return parameter for the resulting cube, in B32 format. + cube - The cube to be inverted. + result - The return parameter for the resulting cube. Return values: NISSY_OK - The cube was inverted succesfully. @@ -177,17 +167,17 @@ Return values: */ long long nissy_inverse( - const char cube[static NISSY_SIZE_B32], - char result[static NISSY_SIZE_B32] + const char cube[static NISSY_SIZE_CUBE], + char result[static NISSY_SIZE_CUBE] ); /* Apply the given sequence of moves on the given cube. Parameters: - cube - The cube to move, in B32 format. + cube - The cube to move. moves - The moves to apply to the cube. Must be a NULL-terminated string. - result - The return parameter for the resulting cube, in B32 format. + result - The return parameter for the resulting cube. Return values: NISSY_OK - The moves were applied succesfully. @@ -200,18 +190,18 @@ Return values: */ long long nissy_applymoves( - const char cube[static NISSY_SIZE_B32], + const char cube[static NISSY_SIZE_CUBE], const char *moves, - char result[static NISSY_SIZE_B32] + char result[static NISSY_SIZE_CUBE] ); /* Apply the single given transformation to the given cube. Parameters: - cube - The cube to be transformed, in B32 format. - transformation - The transformation in (rotation|mirrored) xy format. - result - The return parameter for the resulting cube, in B32 format. + cube - The cube to be transformed. + transformation - The transformation in "(rotation|mirrored) __" format. + result - The return parameter for the resulting cube. Return values: NISSY_OK - The transformation was performed succesfully. @@ -222,37 +212,9 @@ Return values: */ long long nissy_applytrans( - const char cube[static NISSY_SIZE_B32], + const char cube[static NISSY_SIZE_CUBE], const char transformation[static NISSY_SIZE_TRANSFORMATION], - char result[static NISSY_SIZE_B32] -); - -/* -Convert the given cube between the two given formats. - -Parameters: - format_in - The input format. - format_out - The output format. - cube_string - The cube, in format_in format. - result_size - The allocated size of the result array. - result - Return parameter for the cube in format_out format. - -Return values: - NISSY_OK - The conversion was performed succesfully. - NISSY_ERROR_BUFFER_SIZE - The given buffer is too small for the result. - NISSY_ERROR_INVALID_CUBE - The given cube is invalid. - NISSY_ERROR_INVALID_FORMAT - At least one of the given formats is invalid. - NISSY_ERROR_UNKNOWN - An unknown error occurred. - NISSY_ERROR_NULL_POINTER - At least one of 'format_in', 'format_out' or - 'cube_string' arguments is NULL. -*/ -long long -nissy_convert( - const char *format_in, - const char *format_out, - const char *cube_string, - unsigned result_size, - char result[result_size] + char result[static NISSY_SIZE_CUBE] ); /* @@ -267,7 +229,7 @@ Parameters: cp - The corner permutation, 0 <= cp <= 40320 (8!) co - The corner orientation, 0 <= co <= 2187 (3^7) options - Other options. - result - The return parameter for the resulting cube, in B32 format. + result - The return parameter for the resulting cube. Return values: NISSY_OK - The cube was generated succesfully. @@ -281,7 +243,7 @@ nissy_getcube( long long cp, long long co, const char *options, - char result[static NISSY_SIZE_B32] + char result[static NISSY_SIZE_CUBE] ); /* @@ -354,7 +316,7 @@ nissy_checkdata( Solve the given cube using the given solver and options. Parameters: - cube - The cube to solver, in B32 format. + cube - The cube to solver. solver - The name of the solver. nissflag - The flags for NISS (linear, inverse, mixed, or combinations). minmoves - The minimum number of moves for a solution. @@ -386,7 +348,7 @@ Return values: */ long long nissy_solve( - const char cube[static NISSY_SIZE_B32], + const char cube[static NISSY_SIZE_CUBE], const char *solver, unsigned nissflag, unsigned minmoves, -- cgit v1.3 From e391c4624055138f075c0e5772ccaf8ede094b5a Mon Sep 17 00:00:00 2001 From: Sebastiano Tronto Date: Tue, 22 Apr 2025 14:11:38 +0200 Subject: Updated documentation --- README.md | 105 ++++++++++++++++---------------------------------------- src/arch/avx2.h | 2 +- src/nissy.h | 8 ++--- 3 files changed, 34 insertions(+), 81 deletions(-) (limited to 'src/nissy.h') diff --git a/README.md b/README.md index f70c87a..44423a6 100644 --- a/README.md +++ b/README.md @@ -129,27 +129,24 @@ Then you can for example get a cube from a sequence of moves: ``` $ ./run frommoves -moves "R' U' F" -JLQWSVUH=ZLCUABGIVTKH +JLQWSVUH=ZLCUABGIVTKH=A ``` -Or you can get a random cube +The cube format is meant to be easy to copy-paste and read for the +software, but not necessarily intuitive for the user. See below for a +detaileed description. -``` -$ ./run randomcube -WDSQREVX=VBKYDUCJXWAb -``` - -If you don't like this format, you can convert it: +You can also get a random cube ``` -$ ./run convert -fin B32 -fout H48 -cubestr "WDSQREVX=VBKYDUCJXWAb" -UL1 UB0 BL0 FR1 DF0 UR1 DB0 FL0 DR1 DL1 UF0 BR1 DFR2 DBR0 DFL2 UFR2 UBL2 UFL0 UBR2 DBL2 +$ ./run randomcube +WDSQREVX=VBKYDUCJXWAb=A ``` To solve a cube you can use: ``` -$ ./run solve -solver h48h0k4 -n 1 -M 4 -cube "JLQWSVUH=ZLCUABGIVTKH" +$ ./run solve -solver h48h0k4 -n 1 -M 4 -cube "JLQWSVUH=ZLCUABGIVTKH=A" F' U' R ``` @@ -244,8 +241,8 @@ $ python # In the main folder From here you can call the library functions directly, for example: ``` ->>> nissy.compose("NEORSQLH=ZFCYUAGLHTKB", "NEORSQLH=ZFCYUAGLHTKB") -'ASTUGFBH=DACXEZGBLIKF' +>>> nissy.compose('NEORSQLH=ZFCYUAGLHTKB=A', 'NEORSQLH=ZFCYUAGLHTKB=A') +'ASTUGFBH=DACXEZGBLIKF=A' ``` The `python/examples` folder contains some examples, that you @@ -261,94 +258,50 @@ with the comments in nissy.h for more details. NOTE: Support for the Python module is still rudimentary. -## Cube formats - -The cube is represented as a string in one of the following formats, -all explained below: - -* H48 -* LST -* B32 (the default) - -In all of the formats, the permutation of the center pieces is not -stored. This means that the cube is assumed to be in a fixed orientation. - -More formats will become available in the future. - -### Cube format: H48 +## Cube format -In the H48 format, 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). - -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 -``` +This format is a "base 32" encoding of the cube. It is not meant to be +human-readable, but it is compact while still being plain text. Each +piece, including the orientation value, is encoded as a number from 0 +to 31, and this number is then converted to an uppercase letter (0-26) +or to a lowercase letter (27-31). -The cube after the move F looks like this: +The format looks like this: ``` -FL1 UB0 DB0 FR1 UR0 UL0 DL0 DR0 UF1 DF1 BL0 BR0 UFL1 UBL0 DFR1 DBR0 DFL2 UBR0 UFR2 DBL0 +cccccccc=eeeeeeeeeeee=r ``` -Whitespace (including newlines) between pieces is ignored when reading the -cube. A single whitespace character is added between pieces when writing. - -You can find more examples of this format in the utils/cubes folder. - -## Cube format: LST - -In the LST format, a cube is represented by a comma-separated list of -integers. Each piece is represented by an (unsigned) 8-bit integer. The 4 -least-significant bits determine which piece it is, the other 4 determine -the orientation. +Where the first 8 characters represent the corner, the 12 characters +after the first 12 represent the edges and the last character represents +the orientation of the cube with respect to the base orientation. Edges are numbered as follows (see also constants.h): -UF=0 UB=1 DB=2 DF=3 UR=4 UL=5 DL=6 DR=7 FR=8 FL=9 BL=10 BR=11 - -Corners are numbered as follows: - -UFR=0 UBL=1 DFL=2 DBR=3 UFL=4 UBR=5 DFR=6 DBL=7 - -The orientation of the edges is with respect to F/B, the orientation of -corners is with respect to U/D. - -In this format, the solved cube looks like this: - ``` -0, 1, 2, 3, 4, 5, 6, 7, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 +UF=0 UB=1 DB=2 DF=3 UR=4 UL=5 DL=6 DR=7 FR=8 FL=9 BL=10 BR=11 ``` -The cube after the move F looks like this: +Corners are numbered as follows: ``` -36, 1, 38, 3, 66, 5, 64, 7, 25, 1, 2, 24, 4, 5, 6, 7, 16, 19, 10, 11 +UFR=0 UBL=1 DFL=2 DBR=3 UFL=4 UBR=5 DFR=6 DBL=7 ``` -### Cube format: B32 - -This format is a "base 32" encoding of the cube. It is not meant to be -human-readable, but it is compact while still being plain text. Each -piece, including the orientation value, is encoded as a number from 0 -to 31, and this number is then converted to an uppercase letter (0-26) -or to a lowercase letter (27-31). Edges and corners are separated by a -single = character. +At the moment, the only orientation supported is the standard one, as wide +moves, rotations and slice moves are not supported. In this format, the solved cube looks like this: ``` -ABCDEFGH=ABCDEFGHIJKL +ABCDEFGH=ABCDEFGHIJKL=A ``` The cube after the move F looks like this: ``` -MBODSFQH=ZBCYEFGHQTKL +MBODSFQH=ZBCYEFGHQTKL=A ``` -A cube in B32 format is always 21 characters long (22 if the terminating +A cube in B32 format is always 23 characters long (24 if the terminating null character is included). diff --git a/src/arch/avx2.h b/src/arch/avx2.h index ad4ee0d..b1f8a59 100644 --- a/src/arch/avx2.h +++ b/src/arch/avx2.h @@ -134,7 +134,7 @@ inverse(cube_t c) vp = _mm256_andnot_si256(ORIENT_AVX2, vi); ret = _mm256_or_si256(vp, vo); ret = _mm256_and_si256(ret, USED_AVX2); - + return invertco(ret); } diff --git a/src/nissy.h b/src/nissy.h index 963571f..4b2d1eb 100644 --- a/src/nissy.h +++ b/src/nissy.h @@ -2,14 +2,14 @@ This is libnissy (temporarily also known as h48), a Rubik's cube library. All the functions return 0 or a positive integer in case of success and -a negative integer in case of error, unless otherwise specified. See at -the bottom of this file for the list of error codes and their meaning. +a negative integer in case of error, unless otherwise specified. See +below for the list of error codes and their meaning. -TODO: explain cube format +Cubes are passed as strings in the cccccccc=eeeeeeeeeeee=r format, +see the README.md file for more information. Accepted moves are U, D, R, L, F and B, optionally followed by a 2, a ' or a 3. -TODO update when we accept also wide moves, slices and rotations A transformation must be given in the format (rotation|mirrored) (2 letters) -- cgit v1.3