Skip to main content

Using The Toxeus Cloud Solver

The Toxeus Cloud Solver (TCS) incorporates many optimization problem components and parameters. The following sections provide details and examples about each component and parameter.

Michael's first edit

Before Starting​

Make sure that you have the latest version of the Toxeus Node SDK by running the following command in your terminal:

    npm install toxeus-node-sdk@latest

Also, download a working example optimization problem, which contains all currently supported parameters accessible through the Toxeus Cloud Solver (TCS).

Javascript 
const TOXEUS_EMAIL = ""
const TOXEUS_PASSWORD = ""


const { Client, Model } = require('toxeus-node-sdk');
const toxeus = new Client(TOXEUS_EMAIL, TOXEUS_PASSWORD);

// (optional) Set the download directory for the solver results. 
// See https://docs.toxeus.org/docs/solver-parameters#specifying-a-directory-to-save-results-to for more information
// toxeus.setDownloadDirectory("C:/Users/Jill/Desktop/Toxeus");

const model = new Model();

// Beginning of Solver Parameters:

// (optional) Set compression to false to disable compression (default is false). 
// See https://docs.toxeus.org/docs/solver-parameters#specifying-a-directory-to-save-results-to for more information
model.setCompression(false); 

// (optional) Set a problem name, description, and one or more tags 
model.setProblemName("Example Problem For The Toxeus Cloud Solver");
model.setProblemDescription("An example problem which shows how to use the toxeus-node-sdk to formulate and solve a problem using the Toxeus Cloud Solver");
model.setProblemTags(["example-tag-1", "example-tag-2"]);

// (optional) Set the number of starting points the solver should search from in parallel (default: 6, max: 600)
// See https://docs.toxeus.org/docs/solver-parameters#number-of-starting-points for more information
model.setNumberOfStartingPoints(6);

// (optional) Set the number of runs the solver should perform. Each run will be performed by a different instance of the solver running in parallel from a different starting point. (default: 1, max: 10). 
// See https://docs.toxeus.org/docs/solver-parameters#number-of-runs for more information
model.setNumberOfRuns(1);

// (optional) Set the maximum acceptable error of solutions that the solver will return (default: 10)
// See https://docs.toxeus.org/docs/solver-parameters#maximum-acceptable-error for more information
model.setMaximumAcceptableError(10);

// (optional) Set the maximum number of solutions that the solver will return (default: infinity)
// See https://docs.toxeus.org/docs/solver-parameters#maximum-number-of-solutions-to-return for more information
model.setMaximumNumberOfSolutionsToReturn(1000);

// (optional) Set the maximum acceptable objective function value difference from best solutions found (default: infinity)
// See https://docs.toxeus.org/docs/solver-parameters#maximum-acceptable-objective-function-value-difference-from-best-solutions-found for more information
model.setMaximumAcceptableObjectiveFunctionValueDifferenceFromBestSolutionFound(1000000);

// (optional) Set the maximum solver runtime in seconds (default: 900)
// See https://docs.toxeus.org/docs/solver-parameters#maximum-solver-runtime-in-seconds for more information
model.setMaximumSolverRuntimeInSeconds(60);

// (required) Define a new decision variable with a name, lower bound, upper bound, and initial region to select starting points from
// See https://docs.toxeus.org/docs/solver-parameters#decision-variables for more information
model.addDecisionVariable({
     name: "x",
     lower_bound: 10,
     upper_bound: "inf",
     initial_region_to_select_starting_points_from: {
          lower_bound: 11,
          upper_bound: 14
     }
});

model.addDecisionVariable({
     name: "y",
     lower_bound: -20,
     upper_bound: 24,
     initial_region_to_select_starting_points_from: {
          lower_bound: -10,
          upper_bound: 12
     }
});


model.addDecisionVariable({
     name: "z",
     lower_bound: -20,
     upper_bound: 24,
     initial_region_to_select_starting_points_from: {
          lower_bound: 0.1,
          upper_bound: 10
     }
});

// (required if no objective is set) Define a new constraint with an expression and optionally, a name
// See https://docs.toxeus.org/docs/solver-parameters#constraints for more information
model.addConstraint("x + y + z <= 10");

// (required if no constraints are set) Define a new objective function with an expression and type
// See https://docs.toxeus.org/docs/solver-parameters#objective-functions for more information
model.setObjective({
     expression: "(1/x+y+z-3)^2+(x+1/y+z-3)^2+(x+y+1/z-3)^2",
     type: "minimize"
});

// (optional) Set the algorithm parameters for the solver.
model.setAlgorithmParameters({
    "algorithm": "Nelder-Mead",
})

// (optional) Set the penalized points for the solver. These are points that the solver should avoid, such as local optima. The penalty radius is the distance from the point that the solver should avoid.
model.setPenalizedPoints([
    {
         penalized_point:{
              x: 0,
              y: 0,
              z: 0
         },
         penalty_radius: 0.01
    }
])

// (optional) Set the dynamic penalty for the solver.
model.setDynamicPenalty()


// End of Solver Parameters

// Solve the model and save the results to a JSON file
toxeus.Solve(model);

Adding Decision Variables​

Use the addDecisionVariable method to add a decision variable to your problem. Each decision variable present in your problem must be defined using the addDecisionVariable method.Only the decision variable name is required. A complete list of parameters and their default values is shown in the example below.

    model.addDecisionVariable({
        name: "x",
        lower_bound: "-inf",
        upper_bound: "inf",
        initial_region_to_select_starting_points_from: {
            lower_bound: 0,
            upper_bound: 10
        }
    });

The parameters lower_bound and upper_bound specify the boundaries of the decision variable. By default, they are set to -inf (negative infinity) and inf (infinity).

Defining the lower_bound, upper_bound, and initial_region_to_select_starting_points_from paramenters can be beneficial in terms of solution quality, efficiency, and stability. These bounds help ensure that the solver selects starting points and searches only within a feasible and meaningful solution space, which can lead to better and more reliable results.

The initial_region_to_select_starting_points_from parameter specifies the region from which Toxeus Cloud Solver (TCS) will select starting points. The default value is between 0 and 10 for each decision variable. The lower_bound and upper_bound of the initial_region_to_select_starting_points_from parameter must be within the lower_bound and upper_bound of the decision variable, and they must be finite.

⚠️ Warning: Avoid using reserved keywords for variable names. Refer to Supported Operators and Functions for a list of reserved keywords.

Adding Constraints​

Use the addConstraint method to add a constraint to your problem. Each constraint must be defined using this method. Supported relationships include >=, <=, and =.

const TOXEUS_EMAIL = ""
const TOXEUS_PASSWORD = ""

const { Client, Model } = require('toxeus-node-sdk');

const toxeus = new Client(TOXEUS_EMAIL, TOXEUS_PASSWORD);
const model = new Model();

model.addDecisionVariable({name: "x"});
model.addDecisionVariable({name: "y"});
model.addDecisionVariable({name: "z"});

model.addConstraint("x + y + z >= 10");
model.addConstraint("x + y + z <= 15");
model.addConstraint("(x + y)^2 = 10");

toxeus.Solve(model);
tip

The example above shows how to formulate and solve a nonlinear system of equations and inequalities using the Toxeus Cloud Solver.

To solve an optimization problem with an objective function, see the Adding an Objective Function section for more information.

Adding an Objective Function​

Use the setObjective method to define an objective function. The setObjective method takes an object with an expression defining the objective function, and a type indicating whether to minimize or maximize the objective function defined in the expression.

const TOXEUS_EMAIL = ""
const TOXEUS_PASSWORD = ""

const { Client, Model } = require('toxeus-node-sdk');

const toxeus = new Client(TOXEUS_EMAIL, TOXEUS_PASSWORD);
const model = new Model();

model.addDecisionVariable({name: "x"});
model.addDecisionVariable({name: "y"});
model.addDecisionVariable({name: "z"});

model.addConstraint("x + y + z >= 10");
model.addConstraint("x + y + z <= 15");
model.addConstraint("(x + y)^2 = 10");

model.setObjective({
    expression: "x^3+y+z",
    type: "maximize"
});

toxeus.Solve(model);
tip

The example above shows how to formulate and solve a nonlinear optimization problem using the Toxeus Cloud Solver.

The Toxeus Cloud Solver (TCS) only supports problems with one objective.

Optional Solver Parameters​

Here are additional optional parameters that you can set in the solver.

Specifying a Directory to Save Results​

Use the setDownloadDirectory method to specify where results will be saved, and setCompression to enable or disable compression.

  1. Result Storage Location:

    • By default, results are saved to the current working directory.
    • To specify a custom directory, use the setDownloadDirectory method: 
      toxeus.setDownloadDirectory("path/to/your/directory");

  2. Result Compression:

    • Use the setCompression method to enable or disable result compression: 
      model.setCompression(true); // Enable compression
      model.setCompression(false); // Disable compression (default)
    • When enabled, results are compressed using Brotli compression.
    • When disabled (default), results are saved as uncompressed JSON files.

These methods allow you to customize how and where the Toxeus Cloud Solver stores your optimization results, balancing between storage efficiency and ease of access.

Algorithm Parameters (Dictionary)​

Specify the optimization algorithm used by the model. The Toxeus Cloud Solver supports the following local search algorithms:

Local Search Algorithms
  • Powell
  • Nelder-Mead
  • Sbplx
  • Crs
  • Bobyqa
  • newuoa
  • newuoa-bound
  • praxis
  • mma
  • ccsaq
  • slsqp
  • lbfgs
  • tnewton-precond-restart
  • tnewton-precond
  • tnewton-restart
  • tnewton
  • var1
  • var2
  • auglag
  • auglag-eq
const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setAlgorithmParameters({
    "algorithm": "Nelder-Mead",
});

Number of Starting Points (Integer)​

Set the number of parallel starting points for the solver. The default value is 1 and the maximum value is 100.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setNumberOfStartingPoints(5);

Number of Runs (Integer)​

Specifies the number of times the algorithm will execute. Each execution performs a run, which is a parallel local search from all starting points. The number of starting points is determined by the setNumberOfStartingPoints() method. This parameter allows for multiple independent optimization attempts, potentially increasing the chances of finding the global optimum. The default value is 1, meaning a single execution, and the maximum allowed value is 10. Increasing this value can be beneficial for complex problems with multiple local optima.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setNumberOfRuns(2);

Penalized Points (Array of Dictionaries)​

Specify points that the solver should avoid. This feature is useful for excluding known suboptimal regions or infeasible solutions, improving the efficiency of the search process. Each object in the array specifies a point and the radius around it to be penalized.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setPenalizedPoints([
    {
        penalized_point:{
            x_1: 0,
            x_2: 0
        },
        penalty_radius:0
    }
]);

Dynamic Penalty​

Dynamically penalize solutions during the optimization process to avoid known local optima. This is useful when exploring large, complex solution spaces.

Use the setDynamicPenalty method to set the dynamic penalty parameters. Supported modes are:

  • "penalize_all_local_optima_found"
  • "penalize_best_local_optima_found"
  • "penalize_all_local_optima_found_which_satisfy_the_maximum_acceptable_error"

Supported probability distributions are:

  • "uniform"
  • "weibull"
    model.setDynamicPenalty({
        dynamic_penalty_mode: "penalize_all_local_optima_found",
        dynamic_penalty_radii_probability_distribution: { distribution: "uniform" },
        dynamic_penalty_radii_maximum_value: 0.1,
        dynamic_penalty_radii_minimum_value: 0.01
    });

The radius of the dynamic penalty is sampled from the specified probability distribution between dynamic_penalty_radii_minimum_value and dynamic_penalty_radii_maximum_value. Each starting point from which local search is performed will be penalized by an independent and identically distributed random radius sampled from the specified probability distribution.

Maximum Acceptable Error (Float)​

Defines the upper limit of permissible error in the solutions found by the solver. The default setting stands at 0.1, while the floor value is set at 0, signifying that no degree of constraint violation is tolerable.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setMaximumAcceptableError(0.1);

Minimum Acceptable Distance Between Distinct Solutions (Float)​

Sets the minimum acceptable Euclidean distance between distinct solutions. This distance is calculated as the square root of the sum of squared differences between corresponding variables in two solutions. The default value is 0.01 and the minimum value is 0.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setMinimumAcceptableDistanceBetweenDistinctSolutions(0.1);

Note If the minimum acceptable distance is set to 0, the solver will return all solutions found. This may result in a large number of duplicate solutions being returned.

Maximum Number Of Solutions To Return (Integer)​

Limits the number of solutions the solver will return.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setMaximumNumberOfSolutionsToReturn(5);

Maximum Acceptable Objective Function Value Difference From Best Solution Found (Float)​

Set a maximum acceptable objective function value difference from the best solution found. The solver will only return solutions which have an objective function value difference less than this from the best solution found. The default value is infinity or how many solution is found in the runtime of the solver. Change the run time with the parameter setMaximumSolverRuntimeInSeconds.

For example:

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setMaximumAcceptableObjectiveFunctionValueDifferenceFromBestSolutionFound(100);

Note This parameter is only valid for problems with an objective function.

Maximum Solver Runtime In Seconds (Integer)​

Specifies the solver's maximum runtime in seconds. The maximum value is 900 seconds (15 minutes).

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setMaximumSolverRuntimeInSeconds(60);

Problem Name (String)​

Add a descriptive name to the problem.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setProblemName("Example Problem For The Toxeus Cloud Solver");

Problem Description (String)​

Provide a detailed description of the problem.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setProblemDescription("An example problem which shows how to use the toxeus-node-sdk to formulate and solve a problem using the Toxeus Cloud Solver");

Problem Tags ( Array of Strings)​

Adding a problem tag can help you quickly categorize and find your problems.

const { Model } = require('toxeus-node-sdk');
const model = new Model();

model.setProblemTags(["example-tag-1", "example-tag-2"]);