Magic Cube Solver is a program that implements local search and metaheuristic algorithms to solve the optimisation problem posed by a Magic Cube arrangement.

This repository contains implementations of several local search and metaheuristic algorithms for the Magic Cube problem. The algorithms implemented cover the Hill Climbing variants (Steepest Ascent, Sideways Move, Random Restart, and Stochastic), Simulated Annealing, and the Genetic Algorithm. The program aims to find an optimal or near-optimal solution with good time efficiency. It serves them over an HTTP API; the browser front end is a separate repository.

Algorithms

steepest_ascent · sideways_move · random_restart · stochastic · simulated_annealing · genetic

Built with

Go   Fiber   Docker

Links — Live API · Live demo · Front end · Report (PDF, Indonesian)

1. The algorithm list comes from GET /api/v1/algorithms.	2. Either objective function can be requested per solve.
3. A seed makes a run exactly reproducible.	4. The result's swap and objective logs replayed as an animation.

This repository contains an HTTP API built with Go + Fiber. The Three.js 3D interface lives in a separate repository, magic-cube, which calls this API.

Make sure you have installed:

• Go (version 1.25 or newer): https://golang.org/doc/install
• Git: https://git-scm.com/downloads

1. Clone this repository:

   git clone https://github.com/fetiai/magic-cube-core.git
   cd magic-cube-core

2. Run the server:

   go run ./cmd/server

   The server runs at http://127.0.0.1:3000.

3. Run the tests:

   go test ./...
   go vet ./...

Searches run as background jobs rather than as a single request held open until it finishes. Steepest ascent evaluates up to 7750 neighbours per step, and simulated annealing with a cooling_rate close to 1 runs tens of thousands of iterations, so holding an HTTP connection open for that long is not practical.

1. Submit a job — returns a job_id immediately:

   curl -X POST http://127.0.0.1:3000/api/v1/solve \
     -H 'Content-Type: application/json' \
     -d '{
           "algorithm": "simulated_annealing",
           "objective_function": "violated_magic_sum_count",
           "seed": 42,
           "parameters": { "initial_temperature": 10000, "cooling_rate": 0.9999 }
         }'

2. Poll its status:

   curl http://127.0.0.1:3000/api/v1/jobs/<job_id>

3. Fetch the result once the status becomes succeeded:

   curl 'http://127.0.0.1:3000/api/v1/jobs/<job_id>/result?max_points=0'

4. Cancel a job that is still running:

   curl -X DELETE http://127.0.0.1:3000/api/v1/jobs/<job_id>

The list of algorithms, along with their parameters and default values, can be read straight from the server:

curl http://127.0.0.1:3000/api/v1/algorithms

Supplying a seed makes a search exactly repeatable. If seed is omitted, the server picks one and reports it in the result, so the search remains reproducible either way.

genetic differs from the other five algorithms: it generates its own population, so it does not accept an initial_state, and because it is a population method it produces no sequence of swaps to animate (swap_logs is null).

Every setting is read from an environment variable. An invalid value stops the server at startup rather than being silently replaced with the default.

Operational endpoints: /livez, /readyz, /startupz, and /metrics.

docker build -t magic-cube .
docker run -p 3000:3000 magic-cube

Thalita Zahra Sutejo 18222023 thalitazhrr thalitazahras	Report: Problem Description section Report: Objective Function Selection section Report: Implementation of 3 Local Search Algorithms (Hill-Climbing with Sideways Move, Random Restart Hill-Climbing, Stochastic Hill-Climbing) Report: Experimental Results and Analysis (Comparison of How Closely the Algorithms Approach the Global Optimum, and Comparison of the Algorithms' Search Results) Report: Sections 3.1 Conclusion and 3.2 Suggestions README Final revision of the report
Irfan Musthofa 18222056 IrfanMusthofa irfanmusthofa	Source code for the Genetic Algorithm Finalizing the source code for Steepest Ascent Hill-Climbing Finalizing the source code for Hill-Climbing with Sideways Move Finalizing the source code for Random Restart Hill-Climbing Finalizing the source code for Stochastic Hill-Climbing Finalizing the source code for Simulated Annealing Front-end development All testing and debugging Final revision of the report
Eleanor Cordelia 18222059 EleanorCordelia eleanorcordelia	Report: Problem Description section Report: Objective Function Selection section Report: Implementation of 3 Local Search Algorithms (Steepest Ascent Hill-Climbing, Simulated Annealing, Genetic Algorithm) Report: Experimental Results and Analysis (Comparison of Search Duration, Comparison of Algorithm Consistency, Parameter Variation in the Genetic Algorithm) Report: Section 3.2 Suggestions README Final revision of the report
Muhammad Faiz Atharrahman 18222063 faizath faizath	Source code for Steepest Ascent Hill-Climbing Source code for Hill-Climbing with Sideways Move Source code for Random Restart Hill-Climbing Source code for Stochastic Hill-Climbing Source code for Simulated Annealing 3D visualization Chart plotting and the objective value plots in the report