JijZept Solver API Reference

JijZept Solver is a solver for mathematical optimization problems.

Modeling

JijZept Solver requires ommx instance format as input.

Load MPS File

One can load an MPS file using ommx function.

1from ommx.v1 import Instance
2
3# Load MPS file
4ommx_instance = Instance.load_mps("path/to/your/file.mps")

Using JijModeling

One can model optimization problems using jijmodeling. Below is an example of modeling a knapsack problem.

 1import jijmodeling as jm
 2
 3# Item values
 4v = jm.Placeholder("v", ndim=1)
 5# Item weights
 6w = jm.Placeholder("w", ndim=1)
 7# Knapsack capacity
 8W = jm.Placeholder("W")
 9# Number of items
10N = v.len_at(0, latex="N")
11# Decision variable: 1 if item i is packed, 0 otherwise
12x = jm.BinaryVar("x", shape=(N,))
13# Index for items, from 0 to N
14i = jm.Element("i", belong_to=(0, N))
15
16problem = jm.Problem("problem", sense=jm.ProblemSense.MAXIMIZE)
17# Objective function
18problem += jm.sum(i, v[i] * x[i])
19# Constraint: Total weight must not exceed knapsack capacity
20problem += jm.Constraint("WeightLimit", jm.sum(i, w[i] * x[i]) <= W)
21
22# Make instance data
23instance_data = {
24   "v": [10, 13, 18, 31, 7, 15],  # Item values
25   "w": [11, 15, 20, 35, 10, 33], # Item weights
26   "W": 47,                       # Knapsack capacity
27}
28
29# Create OMMX instance
30interpreter = jm.Interpreter(instance_data)
31ommx_instance = interpreter.eval_problem(problem)

Solve

Basic Usage

Following is an example of solving using JijZept Solver with default settings.

1import jijzept_solver
2
3# Solve the problem using 2 threads and a 2.0-second limit for the internal algorithm
4ommx_solution = jijzept_solver.solve(ommx_instance, solve_limit_sec=2.0, num_threads=2)

Advanced Usage

Following is an example of solving using JijZept Solver with specified algorithms and options.

 1import jijzept_solver
 2from jijzept_solver import (
 3    WeightedHillClimbingOption,
 4    WeightedSimulatedAnnealingOption,
 5    LocalILPOption,
 6)
 7
 8# Define solver options
 9whc_op = WeightedHillClimbingOption(
10   num_iters=4,
11   solve_limit_sec_per_iter=0.1,
12)
13wsa_op = WeightedSimulatedAnnealingOption(
14   num_iters=4,
15   solve_limit_sec_per_iter=0.1,
16)
17ilp_op = LocalILPOption(
18   solve_limit_sec=0.5,
19)
20
21# Algorithms will be executed in the order of the list
22options = [whc_op, wsa_op, ilp_op]
23
24# Solve the problem, with log display enabled
25ommx_solution = jijzept_solver.solve(ommx_instance, options=options, log_display=True)

Using Multiple Processes

If you want to use multiple processes, you can specify the options as follows:

 1from jijzept_solver import JijZeptSolverOption
 2
 3# Algorithms will be executed in the order of each list,
 4# and each alghorithm list will be executed in parallel
 5options = JijZeptSolverOption(
 6   processes=[
 7      [whc_op, wsa_op, ilp_op], # First process: WHC -> WSA -> ILP
 8      [ilp_op, ilp_op],         # Second process: ILP -> ILP
 9   ]
10)
11
12# Solve the problem, with log display enabled
13ommx_solution = jijzept_solver.solve(ommx_instance, options=options, log_display=True)

Evaluate Solution

See here.

API Reference

class ALMSimulatedAnnealingOption

Bases: BaseSolverOption

Options for ALM Simulated Annealing algorithm.

allow_optimal_move: bool = True

If True, allow optimal move.

alm_search_option_number: int = 1

Option number for ALM parameter search strategy. 0: Standard method 1: Penalty hybrid method

cancel_token: CancelToken | None = None

Token that can be used to cancel the algorithm.

count_per_iter: int | None = None

Number of sweeps per iteration.

disable_annealing: bool = False

If True, the zero temperature annealing, called hill-climbing, is executed.

normalize_coefficients: bool = True

If True, coefficients of the objective function and constraints are normalized to its maximum coefficient being 1.

num_iters: int

Number of iterations to run the search algorithm.

solve_limit_sec_per_iter: float | None = None

The maximum time allowed for the internal algorithm per iteration in seconds.

class CBCOption

Bases: BaseSolverOption

Options for the CBC solver (via Python-MIP).

solve_limit_sec: float

The maximum time allowed for the internal solver in seconds.

class JijZeptSolverOption

Options for JijZeptSolver

processes: list[SolverOptions]

List of SolverOptions. Each SolverOptions in this list is solved in parallel. SolverOption can be WeightedHillClimbingOption, WeightedSimulatedAnnealingOption, ALMSimulatedAnnealingOption, LocalILPOption, SCIPOption, or CBCOption.

class LocalILPOption

Bases: BaseSolverOption

Options for the Local ILP algorithm.

cancel_token: CancelToken | None = None

Token that can be used to cancel the algorithm.

num_tabu_capacity: int = 10

Number of tabu list capacity.

solve_limit_sec: float

The maximum time allowed for the internal algorithm in seconds.

sparse: bool = True

If True, the algorithm uses a sparse representation.

terminate_if_feasible: bool = False

If True, the algorithm terminates if a feasible solution is found.

zero_objective: bool = False

If True, the algorithm ignore the objective function and search for feasible solutions.

class SCIPOption

Bases: BaseSolverOption

Options for the SCIP solver.

solve_limit_sec: float

The maximum time allowed for the internal solver in seconds.

class WeightedHillClimbingOption

Bases: BaseSolverOption

Options for the Weighted Hill Climbing algorithm.

allow_optimal_move: bool = True

If True, allow optimal move for free variables. When enabled, the algorithm will choose the optimal move instead of a random move.

cancel_token: CancelToken | None = None

Token that can be used to cancel the algorithm.

num_iters: int

Number of iterations to run the search algorithm.

solve_limit_sec_per_iter: float

The maximum time allowed for the internal algorithm per iteration in seconds.

square_linear_equality_penalty: bool = True

If True, squared penalty is applied to linear equality constraints.

square_linear_inequality_penalty: bool = True

If True, squared penalty is applied to linear inequality constraints.

square_quadratic_equality_penalty: bool = False

If True, squared penalty is applied to quadratic equality constraints.

square_quadratic_inequality_penalty: bool = False

If True, squared penalty is applied to quadratic inequality constraints.

class WeightedSimulatedAnnealingOption

Bases: BaseSolverOption

Options for Weighted Simulated Annealing algorithm.

allow_balance_equality_move: bool = True

If True, allow multihot balance move.

allow_balance_inequality_move: bool = True

If True, allow multihot balance inequality move.

allow_multihot_equality_move: bool = True

If True, allow multihot equality move.

allow_multihot_inequality_move: bool = True

If True, allow multihot inequality move.

allow_optimal_move: bool = True

If True, allow optimal move for free variables. When enabled, the algorithm will sometimes choose the optimal move instead of a random move, with probability increasing as annealing progresses.

cancel_token: CancelToken | None = None

Token that can be used to cancel the algorithm.

count_per_iter: int | None = None

Number of sweeps per iteration.

disable_annealing: bool = False

If True, the zero temperature annealing, called hill-climbing, is executed.

make_cbm_greedy: bool | None = None

If True, constraint-based moves use greedy selection (evaluate multiple candidates and pick the best). If False, constraint-based moves apply sampled moves immediately if they pass Metropolis test. If None (default), automatically determined: True for non-linear problems, False for linear problems.

normalize_coefficients: bool = True

If True, coefficients of the objective function and constraints are normalized to its maximum coefficient being 1.

num_cbm_random_sampling: int = 8

Number of random samples to evaluate in greedy constraint-based move selection. Only used when make_cbm_greedy is True. Default is 8.

num_iters: int

Number of iterations to run the search algorithm.

solve_limit_sec_per_iter: float | None = None

The maximum time allowed for the internal algorithm per iteration in seconds.

square_linear_equality_penalty: bool = True

If True, squared penalty is applied to linear equality constraints.

square_linear_inequality_penalty: bool = True

If True, squared penalty is applied to linear inequality constraints.

square_quadratic_equality_penalty: bool = False

If True, squared penalty is applied to quadratic equality constraints.

square_quadratic_inequality_penalty: bool = False

If True, squared penalty is applied to quadratic inequality constraints.

sample(ommx_instance, *, solve_limit_sec=None, time_limit_sec=None, initial_ommx_state=None, num_samples=None, seed=0, options=None, num_threads=None, log_display=False, log_interval_sec=None)

Solve a problem and obtain multiple solutions.

Parameters:

  • solve_limit_sec (float, optional) – The maximum time allowed for the internal solver to run (in seconds). This strictly limits the algorithm’s runtime and excludes data loading or pre/post-processing time. Note that solve_limit_sec and options are mutually exclusive, and at least one of them must be specified.

  • time_limit_sec (float, optional) – Deprecated alias for solve_limit_sec. This will be removed in a future release. Use solve_limit_sec instead.

  • initial_ommx_state (object, optional) – If specified, the search starts from the specified solution.

  • num_samples (int, optional) – Determines the number of samples (solutions). - If unspecified, num_samples is set to 4 by default.

  • seed (int or None, optional) – Determines the seed used to initialize the random number generator used internally. - If specified with an integer, the seed is fixed. - If None is specified, no fixed seed is used and the algorithm is non-deterministic. - If unspecified, a default fixed seed is used so results are reproducible.

  • options (list[SolverOption] | JijZeptSolverOption, optional) – If specified, the solver uses the specified algorithm and its options sequentially. Each algorithm uses the best solution found so far as the initial solution. Note that solve_limit_sec and options are mutually exclusive, and at least one of them must be specified.

  • num_threads (int or None, optional) – The number of threads to use for parallel processing. - Must be at least 2. - If not specified, num_threads is set to max(2, half of physical cores). - If options is specified, this parameter must be None.

  • log_display (bool, optional) – If True, displays runtime metrics during sampling. The logs include process ID, objective value, feasibility status, and elapsed time (in seconds). Defaults to False.

  • log_interval_sec (float, optional) – The interval in seconds between log outputs when log_display is True. Defaults to 1.0 seconds. Has no effect when log_display is False.

  • ommx_instance (ommx.v1.Instance)

Returns:

Samples of solution to the problem.

Return type:

list or object

Examples

Solve QPLIB instance using JijZeptSolver. Time limit is 3 seconds, sampling 4 solutions with log display enabled.

>>> from ommx import dataset
>>> import jijzept_solver
>>> ommx_instance = dataset.qplib("2096")
>>> result = jijzept_solver.sample(ommx_instance, solve_limit_sec=3.0, num_samples=4, log_display=True)
solve(ommx_instance, *, solve_limit_sec=None, time_limit_sec=None, initial_ommx_state=None, seed=0, options=None, num_threads=None, log_display=False, log_interval_sec=None, terminate_if_optimal=True, terminate_if_infeasible=True)

Solve a problem and obtain the best solution.

Parameters:

  • solve_limit_sec (float, optional) – The maximum time allowed for the internal solver to run (in seconds). This strictly limits the algorithm’s runtime and excludes data loading or pre/post-processing time. Note that solve_limit_sec and options are mutually exclusive, and at least one of them must be specified.

  • time_limit_sec (float, optional) – Deprecated alias for solve_limit_sec. This will be removed in a future release. Use solve_limit_sec instead.

  • initial_ommx_state (object, optional) – If specified, the search starts from the specified solution.

  • seed (int or None, optional) – Determines the seed used to initialize the random number generator used internally. - If specified with an integer, the seed is fixed. - If None is specified, no fixed seed is used and the algorithm is non-deterministic. - If unspecified, a default fixed seed is used so results are reproducible.

  • options (list[SolverOption] | JijZeptSolverOption, optional) – If specified, the solver uses the specified algorithm and its options sequentially. Each algorithm uses the best solution found so far as the initial solution. Note that solve_limit_sec and options are mutually exclusive, and at least one of them must be specified.

  • num_threads (int or None, optional) – The number of threads to use for parallel processing. - Must be at least 2. - If not specified, num_threads is set to max(2, half of physical cores). - If options is specified, this parameter must be None.

  • log_display (bool, optional) – If True, displays runtime metrics during solving. The logs include process ID, objective value, feasibility status, and elapsed time (in seconds). Defaults to False.

  • log_interval_sec (float, optional) – The interval in seconds between log outputs when log_display is True. Defaults to 1.0 seconds. Has no effect when log_display is False.

  • terminate_if_optimal (bool, optional) – If True, terminate remaining processes early when any process reports an optimal solution (default). Set to False to continue running all processes even after an optimal solution is detected.

  • ommx_instance (ommx.v1.Instance)

  • terminate_if_infeasible (bool)

Returns:

Solution to the problem.

Return type:

object

Examples

Solve QPLIB instance using JijZeptSolver. Time limit is 3 seconds, with log display enabled.

>>> from ommx import dataset
>>> import jijzept_solver
>>> ommx_instance = dataset.qplib("2096")
>>> result = jijzept_solver.solve(ommx_instance, solve_limit_sec=3.0, log_display=True)
SolverOptions

A type alias for list[SolverOption]. Represents a sequence of solver options to be executed.