Optim_Siman_Solver_Create()
Abstract
Creates an instance of the simulated annealing optimization engine and returns its handle.
Syntax
Optim_Siman_Solver_Create (problem_state_ptr, solution_state_ptr, objective_value_proc, mutate_proc, accept_proc, update_proc, step_update_proc, finish_proc, solution_copy_proc, solution_free_proc, problem_free_proc, temperature_decay_rate, max_attempts_per_run, max_runs_per_step, max_successes_per_step)
| Argument | Type | Description |
|---|---|---|
problem_state_ptr |
void* |
The state of the current problem that is being solved. This state will not be modified by the engine during the optimization process, but is intended to be used for reference in computing possible solutions. It should be a valid input to the objective_value_proc and the problem_free_proc, described below. |
solution_state_ptr |
void* |
An initial solution to the problem. As mutations occur during the execution of the engine, this state may be freed or copied. It should be a valid input to the objective_value_proc, the solution_copy_proc, and the solution_free_proc, described below. |
objective_value_proc |
OptimT_Siman_Objective_Value_Proc |
This procedure should take in the problem_state_ptr and a solution_state_ptr, and return the objective value of the solution. Those solutions that are preferable should result in lower objective values. |
mutate_proc |
OptimT_Siman_Mutate_Proc |
This procedure should take in an OptimT_Siman_Handle and double, and return a new void* that can be used as a solution_state_ptr. This new possible solution to the problem should be based upon the OptimT_Siman Handle’s current soluition_state_ptr, but somehow “mutated”. The double argument serves as a mutation_rate_factor, which the mutate_proc can use to determine the amount of mutation to perform. |
accept_proc |
OptimT_Siman_Mutation_Accept_Notify_Proc |
This procedure simply takes an OptimT_Siman_Handle as its argument. It is called after a new candidate solution is accepted and made into the current solution so that the client can perform any necessary operations at that time. |
update_proc |
OptimT_Siman_Update_Proc |
This procedure takes an OptimT_Siman_Handle and four additional values as arguments. This procedure is called by the engine after every iteration, and is used to update the client on the following statistics of the optimization, which correspond to the four additional arguments: The current “temperature” of the engine, the objective value of the current solution, the number of iterations performed by the engine so far, and the objective value of the current candidate solution. |
step_update_proc |
OptimT_Siman_Step_Update_Proc |
Much like the update_proc, this procedure takes an OptimT_Siman_Handle and an additional value to update the client. This procedure is only called by the engine after every “temperature” step, and solely reports the percentage of considered solutions that were accepted by the engine. |
finish_proc |
OptimT_Siman_Finish_Notify_Proc |
This procedure is called by the engine upon its completion. It must take in an OptimT_Siman_Handle, as well as an EtsT_Compcode. The procedure is used to report back to the client that the engine has finished its optimization, and with what status it has finished. |
solution_copy_proc |
OptimT_Siman_Solution_State_Copy_Proc |
This procedure takes in a void*, which should be able to be cast to a solution state, and then must be able to create and return a copy of any given solution state. |
solution_free_proc |
OptimT_Siman_Solution_State_Free_Proc |
This procedure takes in a void*, which should be able to be case to a solution state, and then it should free the memory used by the solution state. |
problem_free_proc |
OptimT_Siman_Problem_State_Free_Proc |
This procedure takes in a void*, which should be able to be case to a problem state, and then it should free the memory used by the problem state. |
temperature_decay_rate |
double |
At every temperature state, the current temperature is reduced by a certain factor based on the temperature_decay_rate. This argument must be between 0 and 1. A higher temperature_decay_rate will result in the engine reaching a solution faster, but it may be less optimal than a solution found using a lower decay rate. |
max_attempts_per_run |
int |
The engine will schedule a set of mutation attempts, called a “run”. This variable determines how many attempts are performed in one run. |
max_runs_per_step |
int |
The engine will schedule max_runs_per_step in a given temperature step. If no acceptable solution is found by those runs, the engine will terminate, otherwise it will move to the next temperature step. |
max_successes_per_step |
int |
If, in a given temperature step, the engine tries max_successes_per_step successfully accepted mutation attempts, it will move to the next temperature step automatically. |
Return Type
OptimT_Siman_Handle
A handle to the created instance of the optimization engine.
Header
optim_siman.h
Details
This function is used to create a new instance of the optimization engine. It returns a handle that can be then be used in all future optimization calls.
This function will not begin the optimization process, but rather it will set all of the necessary callbacks to be used by the engine, as well as a few other necessary parameters, documented in the argument description section.
Typically, after calling Optim_Siman_Solver_Create(), the next call made will be Optim_Siman_Solver_Execute(). When the optimization process has completed, the returned OptimT_Siman_Handle should be destroyed using Optim_Solver_Destroy().