Getting Started

Welcome to the Toxeus Cloud Solver documentation! Our documentation is designed to provide you with the resources and information you need to utilize the Toxeus Cloud Solver to solve optimization problems and find solutions to systems of nonlinear equations and inequalities.

To make it easy for users to solve problems using the Toxeus Cloud Solver, we have developed an open-source Node.js package, the toxeus-node-sdk. This page provides a step-by-step guide on how to install and use the toxeus-node-sdk to formulate and solve problems using the Toxeus Cloud Solver.

These are the steps required to use the Toxeus Cloud Solver:

Create a Toxeus account
Install pre-requisite software

Solve an example problem with the Toxeus Cloud Solver

tip

Minimal programming experience is needed to complete these steps and work with the Toxeus Cloud Solver.

Create a Toxeus account

Step 1 - Go to the Toxeus Cloud Solver website

Create a free Toxeus Account.

Note: You will need your Toxeus Username (your email) and Password to solve problems with the Toxeus Cloud Solver.

tip

New users are given ample free credit to complete this demo and become familiar with the Toxeus Cloud Solver. If you run out of free credit or if you need to use the Toxeus Cloud Solver in a capacity not supported by the Free Tier Limits, you can upgrade your account to a paid subscription by logging in to your Toxeus Account, and selecting "Manage Billing". You can cancel your subscription at any time, and you only pay for what you use.

Install pre-requisite software

In order to use the Toxeus Cloud Solver, you will need to perform the following steps:

Step 1 - Download & install Node.js

Download and run the Windows (.msi) or macOS (.pkg) Installer file from the official Node.js website.

alt text

Note: While installing Node.js, the Node Package Manager (NPM) will automatically be installed on your computer. NPM is the tool that you will use to download and install the toxeus-node-sdk package.

Before proceeding to Step 2, please verify that you have successfully installed both Node.js and the NPM by opening a command prompt on your computer (see tip below) and running the following command:

node -v && npm -v

You should see an output of the version of Node.js and NPM that you have installed on your computer. For example:

v20.17.0
10.8.2

tip

In Windows, you can open a terminal / command prompt by typing cmd in the Windows search bar. In Mac, you can open a terminal by typing terminal in the Mac spotlight search bar.

Step 2 - Create a new folder for your project

Create a new folder for your Toxeus project. You can do this through your file explorer or using the command line:

On Windows (Command Prompt):
```
mkdir ToxeusProject
cd ToxeusProject
```
On macOS or Linux (Terminal):
```
mkdir ToxeusProject
cd ToxeusProject
```
This new folder will be where you install the Toxeus SDK and store your project files.

Step 3 - Install the toxeus-node-sdk

After you have completed Step 1 and Step 2, and you have Node.js and NPM installed and are in your project folder, you can download and install the toxeus-node-sdk package by running the following command in your terminal / command prompt:

npm install toxeus-node-sdk@latest

Solve an example problem

Step 1 - Download the demo Node.js script which uses the toxeus-node-sdk to solve an optimization problem with the Toxeus Cloud Solver

tip

On Windows, after you navigate to the link, right-click on the page and select "Save As" or "Save Page As" and for "Save as type", select "All Files". On Mac, after you navigate to the link, right-click on the page and select "Download Linked File As."

Your computer may try to save the file with the extension .txt instead of .js. If this happens, you can change the extension by right clicking on the file, selecting "Rename", and then changing the extension to .js.

Note - For this example, we will assume that you made a new folder on your Desktop called "Toxeus" and that you downloaded the demo Node.js script there. On Windows, if your username was Jill, the path to the script will be: C:\Users\Jill\Desktop\Toxeus\Toxeus_Cloud_Solver_JavaScript_SDK_demo.js. On Mac, if your username was Jill, the path to the script will be: /Users/Jill/Desktop/Toxeus/Toxeus_Cloud_Solver_JavaScript_SDK_demo.js. We will need to know the path to our script in the next steps of this tutorial.

The Javascript code that you will download is shown below.

Javascript

const TOXEUS_EMAIL = ""
const TOXEUS_PASSWORD = ""


const { Client, Model } = require('toxeus-node-sdk');
const toxeus = new Client(TOXEUS_EMAIL, TOXEUS_PASSWORD);
// toxeus.setDownloadDirectory("C:/Users/Jill/Desktop/Toxeus");

const model = new Model();

// Beginning of Solver Parameters:

// (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 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"
});


// End of Solver Parameters

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

Step 3 - Open the downloaded Node.js script and input your Email and Password

Open the downloaded Node.js script in your favorite text editor.

tip

On Windows, you can edit this file using the Notepad application by right clicking on the file, selecting "Open With", and then selecting "Notepad". On Mac, you can edit this file using the TextEdit application by right clicking on the file, selecting "Open With", and then selecting "TextEdit".

Edit the first two lines of the downloaded Node.js script so that they contain the email and password that you signed up with for your Toxeus Account.

For example, if you signed up with the email jill@toxeus.org and the password MyPassword!, you would change the first two lines which currently look like this:

const TOXEUS_EMAIL = ""
const TOXEUS_PASSWORD = ""

to look like this:

const TOXEUS_EMAIL = "jill@toxeus.org"
const TOXEUS_PASSWORD = "MyPassword!"

After editing the above two lines, save the file.

After you save the file, it should look something like this:

Javascript

const TOXEUS_EMAIL = "jill@toxeus.org"
const TOXEUS_PASSWORD = "MyPassword!"


const { Client, Model } = require('toxeus-node-sdk');
const toxeus = new Client(TOXEUS_EMAIL, TOXEUS_PASSWORD);
// toxeus.setDownloadDirectory("C:/Users/Jill/Desktop/Toxeus");

const model = new Model();

// Beginning of Solver Parameters:

// (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 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"
});


// End of Solver Parameters

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

Step 4 - Run the demo Node.js script which uses the toxeus-node-sdk to solve an optimization problem with the Toxeus Cloud Solver

If your username on your computer was Jill and you downloaded the demo Node.js script into a folder named "Toxeus" on your Desktop, you can run the demo Node.js script by running the following command from your command prompt:

On Windows:

node "C:\Users\Jill\Desktop\Toxeus\Toxeus_Cloud_Solver_JavaScript_SDK_demo.js"

On Mac:

node "/Users/Jill/Desktop/Toxeus/Toxeus_Cloud_Solver_JavaScript_SDK_demo.js"

If the above command runs successfully, you should see two new JSON files in the folder where you downloaded the demo Node.js script.

The file that ends with the suffix request.default.json contains the problem data sent from your computer to the Toxeus Cloud Solver. If you open it in a text editor, it will look like this:

JSON

{
   "problem_type": "optimization",
   "problem_constraints": [
      {
         "constraint": "x + y + z <= 10"
      }
   ],
   "problem_variables": [
      {
         "name": "x",
         "lower_bound": 10,
         "upper_bound": "inf",
         "initial_region_to_select_starting_points_from": {
            "lower_bound": 11,
            "upper_bound": 14
         }
      },
      {
         "name": "y",
         "lower_bound": -20,
         "upper_bound": 24,
         "initial_region_to_select_starting_points_from": {
            "lower_bound": -10,
            "upper_bound": 12
         }
      },
      {
         "name": "z",
         "lower_bound": -20,
         "upper_bound": 24,
         "initial_region_to_select_starting_points_from": {
            "lower_bound": 0.1,
            "upper_bound": 10
         }
      }
   ],
   "maximum_acceptable_error": 10,
   "minimum_acceptable_distance_between_distinct_solutions": 0.01,
   "maximum_solver_runtime_in_seconds": 60,
   "number_of_starting_points": 1,
   "number_of_runs": 1,
   "problem_name": "Example Problem For The Toxeus Cloud Solver",
   "problem_description": "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": [
      {
         "tag": "example-tag-1"
      },
      {
         "tag": "example-tag-2"
      }
   ],
   "maximum_number_of_solutions_to_return": 1000,
   "maximum_acceptable_objective_function_value_difference_from_best_solution_found": 1000000,
   "problem_objective_function": [
      {
         "expression": "(1/x+y+z-3)^2+(x+1/y+z-3)^2+(x+y+1/z-3)^2",
         "type": "minimize"
      }
   ]
}

The file that ends with the suffix response.default.json contains the solution(s) that were found by the Toxeus Cloud Solver. If you open it in a text editor, it will look like this:

JSON

{
    "solutions": [
        {
            "algorithm_parameters": null,
            "amount_of_constraint_violation": [
                0
            ],
            "max_error": 0,
            "number_of_algorithm_iterations": 1,
            "number_of_objective_function_evaluations_performed_during_optimization": 142,
            "number_of_solutions_found": 1,
            "objective_function_value": 0,
            "ran_out_of_time": false,
            "request_id_of_solver_that_found_solution": "b519be1b-de0f-4cdd-857d-2c4329e49a65",
            "run_number": 1,
            "search_converged": true,
            "solution": [
                12.166213589197591,
                -4.252443789585796,
                0.782074338257649
            ],
            "starting_point": [
                12.166213581127817,
                -4.252443844223388,
                0.7820744202140356
            ],
            "starting_point_number": "1:1",
            "time_spent_evaluating_objective_function_during_optimization": 1.3480000000000011e-9,
            "time_spent_parsing_constraints": 0.000339,
            "time_spent_solving": 1.3480000000000011e-9,
            "total_error": 0
        },
    ],
    "total_gigabyte_seconds_used_by_solver": 23.16,
    "total_gigabyte_seconds_charged_by_solver": 24,
    "solver_start_time": 1725969092.774,
    "time_of_request_completion": 1725969094.363
}

Create a Toxeus account​

Step 1 - Go to the Toxeus Cloud Solver website​

Install pre-requisite software​

Step 1 - Download & install Node.js​

Step 2 - Create a new folder for your project​

Step 3 - Install the toxeus-node-sdk​

Solve an example problem​

Step 1 - Download the demo Node.js script which uses the toxeus-node-sdk to solve an optimization problem with the Toxeus Cloud Solver​

Step 3 - Open the downloaded Node.js script and input your Email and Password​

Step 4 - Run the demo Node.js script which uses the toxeus-node-sdk to solve an optimization problem with the Toxeus Cloud Solver​