JijDA4Sampler

The Digital Annealer (DA) is a high-performance Ising machine provided by Fujitsu. DA achieves rapid optimization computations due to its advanced parallelization algorithm. A distinguishing feature of DA is its capability to specify constraint conditions separately. Because of this, it serves as a potent solver even for problems with constraint conditions. JijZept can automatically determine the constraint conditions to be specified to DA from Problems described in JijModeling and convert them to DA's schema. This means JijZept users can harness the full potential of DA without any special actions.

The JijDA4Sampler supports QUBO API V4, called “DA4” here. There are certain limitations to the mathematical models that JijDA4Sampler can handle:

• the objective function and equality constraints must be at most quadratic.
• inequality constraints must be linear.

Usage

1. Update the config.toml by adding the [default.thirdparty-setting] section. Include the following two items:

   • da4_url: Endpoint for DA4. You can find the exact endpoint in the “Servers” dropdown of the "Digital Annealer API Reference (QUBO API V4)" (English, Japanese).
   • da4_token: The API key to use DA4. For more specific, consult the "API Getting Started" guide (English, Japanese).

   [default]
   url = "https://api.m.jijzept.com/"
   token = "JIJ_ZEPT_API_KEY"
   
   [default.thirdparty-setting]
   da4_url = "DIGITAL_ANNEALER_V4_ENDPOINT" # Optional: Basically works without it.
   da4_token = "DIGITAL_ANNEALER_V4_TOKEN"

2. Use the two classes provided by the jijzept and run the method sample_model in the JijDA4Sampler class:

   • JijDA4Sampler: a class to sample using the DA4.
   • JijDA4SolverParameters: a class to set parameters specifically for the DA4.

   from jijzept import JijDA4Sampler, JijDA4SolverParameters
   
   sampler = JijDA4Sampler(config="./config.toml")
   parameters = JijDA4SolverParameters(time_limit_sec=5)
   
   response = sampler.sample_model(
       model=problem,
       feed_dict=instance_data,
       parameters=parameters,
   )

info

If you want to configure da4_url and da4_token without using the configuration file, you can do so as follows:

sampler = JijDA4Sampler(
    url="https://api.m.jijzept.com/",
    token="JIJ_ZEPT_API_KEY",
    da4_url="DIGITAL_ANNEALER_V4_ENDPOINT",
    da4_token="DIGITAL_ANNEALER_V4_TOKEN",
)

What does JijZept automatically tune?

JijZept automatically detects the appropriate constraints for specification in DA4 and generates a schema tailored for DA4 using these constraints. As a result, JijZept users can harness the performance of DA4 without needing an in-depth understanding of its schema. This section explains the conditions under which the automatic detection operates.

1. One-Way One-Hot Constraints Detection

JijZept identifies constraints as One-Way One-Hot based on the following conditions:

• The constraint is an equality.
• The number of dimensions of the decision variable is 1.
• All the coefficients and a bias term share the same value.

Examples

• $\sum_{i=0}^{N-1} x_{i,j} = 1,\ \forall i \in \{0,\ldots, M-1\}$
• $\sum_{e \in E} ax_{e,s} = a,\ \forall s \in S, \ a \neq 0$

2. Two-Way One-Hot Constraints Detection

JijZept identifies constraints as Two-Way One-Hot based on the following conditions:

• The constraint is an equality.
• The coefficients of the decision variables are not explicitly described.
• The constraint comprises just one type of decision variable.
• The number of dimensions of the decision variable is 1.

Example

• For the 2-dimensional TSP constraint (See the tutorial page of "Traveling Salesman Problem"): $\sum_{i}x_{i,t}=1,\ \forall t, \sum_{t}x_{i,t}=1,\ \forall i$

3. Priority between One-Hot Constraints

When a scenario arises where both One-Way and Two-Way One-Hot constraints are valid:

• JijZept favors the one with a greater number of decision variables.
• If both handle an equal count, Two-Way One-Hot is the preferred choice.

4. Automatic Detection of Inequality Constraints

JijZept can detect linear inequality constraints, relieving users from the need to manually describe the "Inequalities" schema in the DA4. To adjust constraint weights, simply use the inequalities_lambda parameter within JijDA4Sampler.sample_model.

Here’s a sample code to assign a weight of 10 to a linear inequality constraint termed “my inequality constraint”:

import jijmodeling as jm
from jijzept import JijDA4Sampler

N = jm.Placeholder("N")
x = jm.BinaryVar("x", shape=(N,))
problem = jm.Problem("problem")
problem += jm.Constraint("my inequality constraint", x[:].sum() <= 3) # linear inequality constraint

instance_data = {"N": 5}

sampler = JijDA4Sampler(config="./config.toml")
response = sampler.sample_model(
    model=problem,
    feed_dict=instance_data,
    inequalities_lambda={"my inequality constraint": 10},
)

Parameters

JijDA4SolverParameters

name	type	default	description
time_limit_sec	int	10	Maximum running time of DA in seconds. For more details, please refer to the description of the time_limit_sec parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
target_energy	Optional[float]	None	Threshold energy for fast exit. If you don't set it, the calculation will run without any target energy. For more details, please refer to the description of the target_energy parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
num_run	int	16	The number of parallel attempts of each groups. For more details, please refer to the description of the num_run parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
num_group	int	1	The number of groups of parallel attempts. For more details, please refer to the description of the num_group parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
num_output_solution	int	5	The number of output solutions of each groups. For more details, please refer to the description of the num_output_solution parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
gs_level	int	5	Level of the global search. For more details, please refer to the description of the gs_level parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
gs_cutoff	int	8000	Global search cutoff level. For more details, please refer to the description of the gs_cutoff parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
one_hot_level	int	3	Level of the one-hot constraint search. For more details, please refer to the description of the one_hot_level parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
one_hot_cutoff	int	100	Level of the convergence for one-hot constraint search. For more details, please refer to the description of the one_hot_cutoff parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
internal_penalty	int	0	Mode of one-hot constraint internal generation. For more details, please refer to the description of the internal_penalty parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
penalty_auto_mode	int	1	Coefficient adjustment mode. For more details, please refer to the description of the penalty_auto_mode parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
penalty_coef	int	1	Coefficient of the constraint term. For more details, please refer to the description of the penalty_coef parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
penalty_inc_rate	int	150	Parameters for automatic adjustment of constraint terms. For more details, please refer to the description of the penalty_inc_rate parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.
max_penalty_coef	int	0	Maximum constraint term coefficent. For more details, please refer to the description of the max_penalty_coef parameter in the "FujitsuDA3Solver" item under the "Schemas" section of the API reference.

JijDA4Sampler.sample_model

name	type	default	description
fixed_variables	Optional[FixedVariables]	None	The dictionary of variables to be fixed.
parameters	Optional[JijDA4SolverParameters]	None	Parameters for JijDA4Sampler.
inequalities_lambda	dict[str, int]	{}	Pairs of inequality constraint names and their coefficients. If your Problem object have an inequality constraint but you do not set a coefficient for it, the coefficient is automatically set to 1. This matches the default value of the lambda parameter in "Inequalities". For more details, please refer to the description of the lambda parameter in the "Inequalities" item under the "Schemas" section of the API reference.
normalize_qubo	bool	False	If True, during the creation of QUBO, both the objective function and the constraints are individually normalized by their largest absolute coefficients.
max_wait_time	Optional[Union[int, float]]	None	The number of timeout [sec] for post request. If None, 60 (one minute) will be set.
sync	bool	True	If True, synchronous mode is enabled.
queue_name	Optional[str]	None	Queue name
api_version	str	v4	The API version of Digital Annealer. JijZept suppoorts "v4" and "v3c". Defaults to "v4".