Dynex SDK
Module contents
Dynex SDK (beta) Neuromorphic Computing Library Copyright (c) 2021-2023, Dynex Developers
All rights reserved.
- Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- class dynex.BQM(bqm, relabel=True, logging=True)[source]
Bases:
objectCreates a model, which can be used by the sampler based on a Binary Quadratic Model (BQM) problem. The Dynex sampler needs a “model” object for sampling. Based on the problem formulation, multiple model classes are supported.
- Parameters
- bqm
The BQM to be used for this model (class:dimod.BinaryQuadraticModel)
- relabel
Defines if the BQM’s variable names should be relabeled (bool)
- logging
True to show model creation information, False to silence outputs (bool)
- Returns
class:dynex.model
- Example
Dimod’s dimod.binary.BinaryQuadraticModel (BQM) contains linear and quadratic biases for problems formulated as binary quadratic models as well as additional information such as variable labels and offset.
bqm = dimod.BinaryQuadraticModel({'x1': 1.0, 'x2': -1.5, 'x3': 2.0}, {('x1', 'x2'): 1.0, ('x2', 'x3'): -2.0}, 0.0, dimod.BINARY) model = dynex.BQM(bqm)
- class dynex.CQM(cqm, relabel=True, logging=True)[source]
Bases:
objectCreates a model, which can be used by the sampler based on a Constraint Quadratic Model (CQM) problem. The Dynex sampler needs a “model” object for sampling. Based on the problem formulation, multiple model classes are supported.
- Parameters
- cqm
The BQM to be used for this model (class:dimod.ConstraintQuadraticModel)
- relabel
Defines if the BQM’s variable names should be relabeled (bool)
- logging
True to show model creation information, False to silence outputs (bool)
- Returns
class:dynex.model
- Example
Dimod’s dimod.ConstrainedQuadraticModel (CQM) contains linear and quadratic biases for problems formulated as constrained quadratic models as well as additional information such as variable labels, offsets, and equality and inequality constraints.
num_widget_a = dimod.Integer('num_widget_a', upper_bound=7) num_widget_b = dimod.Integer('num_widget_b', upper_bound=3) cqm = dimod.ConstrainedQuadraticModel() cqm.set_objective(-3 * num_widget_a - 4 * num_widget_b) cqm.add_constraint(num_widget_a + num_widget_b <= 5, label='total widgets') model = dynex.CQM(cqm)
- class dynex.DynexSampler(model, logging=True, mainnet=True, description='Dynex SDK Job', test=False)[source]
Bases:
objectInitialises the sampler object given a model.
- Parameters
- logging
Defines if the sampling process should be quiet with no terminal output (FALSE) or if process updates are to be shown (bool)
- mainnet
Defines if the mainnet (Dynex platform sampling) or the testnet (local sampling) is being used for sampling (bool)
- description
Defines the description for the sampling, which is shown in Dynex job dashboards as well as in the market place (string)
- Returns
class:dynex.samper
- Example
sampler = dynex.DynexSampler(model)
- sample(num_reads=32, annealing_time=10, clones=1, switchfraction=0.0, alpha=20, beta=20, gamma=1, delta=1, epsilon=1, zeta=1, minimum_stepsize=6e-08, debugging=False)[source]
The main sampling function:
- Parameters
- num_reads
Defines the number of parallel samples to be performed (int value in the range of [32, MAX_NUM_READS] as defined in your license)
- annealing_time
Defines the number of integration steps for the sampling. Models are being converted into neuromorphic circuits, which are then simulated with ODE integration by the participating workers (int value in the range of [1, MAX_ANNEALING_TIME] as defined in your license)
- clones
Defines the number of clones being used for sampling. Default value is 1 which means that no clones are being sampled. Especially when all requested num_reads will fit on one worker, it is desired to also retrieve the optimum ground states found from more than just one worker. The number of clones runs the sampler for n clones in parallel and aggregates the samples. This ensures a broader spectrum of retrieved samples. Please note, it the number of clones is set higher than the number of available threads on your local machine, then the number of clones processed in parallel is being processed in batches. Clone sampling is only available when sampling on the mainnet. (integer value in the range of [1,128])
- switchfraction
Defines the percentage of variables which are replaced by random values during warm start samplings (double in the range of [0.0, 1.0])
- alpha
The ODE integration of the QUBU/Ising or SAT model based neuromorphic circuits is using automatic tuning of these parameters for the ODE integration. Setting values defines the upper bound for the automated parameter tuning (double value in the range of [0.00000001, 100.0] for alpha and beta, and [0.0 and 1.0] for gamma, delta and epsilon)
- beta
The ODE integration of the QUBU/Ising or SAT model based neuromorphic circuits is using automatic tuning of these parameters for the ODE integration. Setting values defines the upper bound for the automated parameter tuning (double value in the range of [0.00000001, 100.0] for alpha and beta, and [0.0 and 1.0] for gamma, delta and epsilon)
- gamma
The ODE integration of the QUBU/Ising or SAT model based neuromorphic circuits is using automatic tuning of these parameters for the ODE integration. Setting values defines the upper bound for the automated parameter tuning (double value in the range of [0.00000001, 100.0] for alpha and beta, and [0.0 and 1.0] for gamma, delta and epsilon)
- delta
The ODE integration of the QUBU/Ising or SAT model based neuromorphic circuits is using automatic tuning of these parameters for the ODE integration. Setting values defines the upper bound for the automated parameter tuning (double value in the range of [0.00000001, 100.0] for alpha and beta, and [0.0 and 1.0] for gamma, delta and epsilon)
- epsilon
The ODE integration of the QUBU/Ising or SAT model based neuromorphic circuits is using automatic tuning of these parameters for the ODE integration. Setting values defines the upper bound for the automated parameter tuning (double value in the range of [0.00000001, 100.0] for alpha and beta, and [0.0 and 1.0] for gamma, delta and epsilon)
- zeta
The ODE integration of the QUBU/Ising or SAT model based neuromorphic circuits is using automatic tuning of these parameters for the ODE integration. Setting values defines the upper bound for the automated parameter tuning (double value in the range of [0.00000001, 100.0] for alpha and beta, and [0.0 and 1.0] for gamma, delta and epsilon)
- minimum_stepsize
The ODE integration of the QUBU/Ising or SAT model based neuromorphic circuits is performig adaptive stepsizes for each ODE integration forward Euler step. This value defines the smallest step size for a single adaptive integration step (double value in the range of [0.0000000000000001, 1.0])
- debugging
Only applicable for test-net sampling. Defines if the sampling process should be quiet with no terminal output (FALSE) or if process updates are to be shown (TRUE) (bool)
- Returns
Returns a dimod sampleset object class:dimod.sampleset
- Example
import dynex import dimod # Define the QUBU problem: bqmodel = dimod.BinaryQuadraticModel({0: -1, 1: -1}, {(0, 1): 2}, 0.0, dimod.BINARY) # Sample the problem: model = dynex.BQM(bqmodel) sampler = dynex.DynexSampler(model) sampleset = sampler.sample(num_reads=32, annealing_time = 100) # Output the result: print(sampleset)
╭────────────┬───────────┬───────────┬─────────┬─────┬─────────┬───────┬─────┬──────────┬──────────╮ │ DYNEXJOB │ ELAPSED │ WORKERS │ CHIPS │ ✔ │ STEPS │ LOC │ ✔ │ ENERGY │ ✔ │ ├────────────┼───────────┼───────────┼─────────┼─────┼─────────┼───────┼─────┼──────────┼──────────┤ │ 3617 │ 0.07 │ 1 │ 0 │ 32 │ 100 │ 0 │ 1 │ 0 │ 10000.00 │ ╰────────────┴───────────┴───────────┴─────────┴─────┴─────────┴───────┴─────┴──────────┴──────────╯ ╭─────────────────────────────┬───────────┬─────────┬───────┬──────────┬───────────┬───────────────┬──────────╮ │ WORKER │ VERSION │ CHIPS │ LOC │ ENERGY │ RUNTIME │ LAST UPDATE │ STATUS │ ├─────────────────────────────┼───────────┼─────────┼───────┼──────────┼───────────┼───────────────┼──────────┤ │ *** WAITING FOR WORKERS *** │ │ │ │ │ │ │ │ ╰─────────────────────────────┴───────────┴─────────┴───────┴──────────┴───────────┴───────────────┴──────────╯ [DYNEX] FINISHED READ AFTER 0.07 SECONDS [DYNEX] PARSING 1 VOLTAGE ASSIGNMENT FILES... progress: 100% 1/1 [00:05<00:00, 5.14s/it] [DYNEX] SAMPLESET LOADED [DYNEX] MALLOB: JOB UPDATED: 3617 STATUS: 2 0 1 energy num_oc. 0 0 1 -1.0 1 ['BINARY', 1 rows, 1 samples, 2 variables]
- class dynex.SAT(clauses, logging=True)[source]
Bases:
objectCreates a model, which can be used by the sampler based on a SAT problem. The Dynex sampler needs a “model” object for sampling. Based on the problem formulation, multiple model classes are supported.
- Parameters
- clauses
List of sat caluses for this model (list)
- logging
True to show model creation information, False to silence outputs (bool)
- Returns
class:dynex.model
- Example
Dimod’s dimod.binary.BinaryQuadraticModel (BQM) contains linear and quadratic biases for problems formulated as binary quadratic models as well as additional information such as variable labels and offset.
clauses = [[1, -2, 3], [-1, 4, 5], [6, 7, -8], [-9, -10, 11], [12, 13, -14], [-1, 15, -16], [17, -18, 19], [-20, 2, 3], [4, -5, 6], [-7, 8, 9], [10, 11, -12], [-13, -14, 15], [16, 17, -18], [-19, 20, 1], [2, -3, 4], [-5, 6, 7], [8, 9, -10], [-11, -12, 13], [14, 15, -16], [-17, 18, 19]] model = dynex.SAT(clauses)
- dynex.account_status()[source]
Shows the status of the Dynex SDK account:
ACCOUNT: <YOUR ACCOUNT IDENTIFICATION> API SUCCESSFULLY CONNECTED TO DYNEX ----------------------------------- ACCOUNT LIMITS: MAXIMUM NUM_READS: 5,000,000 MAXIMUM ANNEALING_TIME: 10,000 MAXIMUM JOB DURATION: 60 MINUTES USAGE: TOTAL USAGE: 97,699,614,400 / 10,000,000,000,000 ( 0.976996144 %) NUM_READS x ANNEALING_TIME
- dynex.aes_encrypt(raw)[source]
Internal Function
- Returns
Returns the encrypted string of ‘raw’ with an AES Key privided by the Dynex platform (string)
- dynex.check_api_status(logging=False)[source]
Internal Function
Dynex API call to output the status of the Dynex SDK account
- Returns
TRUE if the API call was successful, FALSE if the API call was not successful (bool)
- dynex.convert_bqm_to_qubo(bqm, relabel=True, logging=True)[source]
Internal Function
Converts a given Binary Quadratic Model (BQM) problem into a wncf file which is being used by the Dynex platform workers for the sampling process. Every BQM can be converted to a QUBO formulation in polynomial time (and vice-versa) without loss of functionality. During the process, variables are re-labeld and mapped to integer values in the range of [0, NUM_VARIABLES}. The mapping is being made available in sampler.variable_mappings and is used for constructing the returned sampleset object.
- Notes
The BQM needs to have at least one defined weight, otherwise an exception is thrown
Double values of weights are being converted to integer values with the factor ‘PRECISION’
The value for PRECISION is determined automatically with function 10 ** (np.floor(np.log10(max_abs_coeff)) - 4)
- Parameters
- bqm
the Binary Quadratic Model to be converted (class:dimod.BinaryQuadraticModel)
- Returns
- clauses
A list of all clauses (list)
- num_variables
number of variables (int)
- num_clauses
number of clauses (int)
- mappings
variable mappings original -> integer value (dict)
- precision
precision of conversion (double)
- bqm
class:dimod.BinaryQuadraticModel
- dynex.find_largest_value(lst)[source]
Internal Function
- Returns
The largest variable in a list of clauses (int)
- dynex.generate_hash(filename)[source]
Internal Function
- Returns
Returns the sha3-256 hash of a given file (string)
- dynex.generate_job_api(sampler, annealing_time, switchfraction, num_reads, alpha=20, beta=20, gamma=1, delta=1, epsilon=1, zeta=1, minimum_stepsize=6e-08, logging=True)[source]
Internal Function
Dynex API call to generate a new job
- Returns
TRUE if the job was successfully created, FALSE if there was a problem with generating the job (bool)
- dynex.get_status_details_api(JOB_ID, all_stopped=False)[source]
Internal Function
Dynex API call to retrieve status of the job
- Returns
- LOC_MIN
Lowest value of global falsified soft clauses of the problem which is being sampled (int)
- ENERGY_MIN
Lowest QUBO energy of the problem which is being sampled (double)
- CHIPS
The number of chips which are currently sampling (int)
- retval
Tabulated overview of the job status, showing workers, found assignments, etc. (string)
- dynex.ksat(clauses)[source]
Internal Function
Converts a k-sat formulation into 3-sat.
- Returns
List of clauses of the converted 3-sat (list)
- dynex.sample_thread(q, x, model, logging, mainnet, description, num_reads, annealing_time, switchfraction, alpha, beta, gamma, delta, epsilon, zeta, minimum_stepsize)[source]
Internal Function which creates a thread for clone sampling
- dynex.sat_creator(variables, clause_type, dummy_number, results_clauses)[source]
Internal Function
Converts a k-sat clause to a number of 3-sat clauses.
- Parameters
- variables
- clause_type
- dummy_number
- results_clauses
- Returns
- dummy_number
- results_clauses
- dynex.save_cnf(clauses, filename, mainnet)[source]
Internal Function
Saves the model as an encrypted .bin file locally in /tmp as defined in dynex.ini
- dynex.save_wcnf(clauses, filename, num_variables, num_clauses, mainnet)[source]
Internal Function
Saves the model as an encrypted .bin file locally in /tmp as defined in dynex.ini
- dynex.test()[source]
Performs test of the dynex.ini settings. Successful completion is required to start using the sampler.