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:

1. Create a Toxeus account
2. Install pre-requisite software
3. Solve an example problem with the Toxeus Cloud Solver

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.

|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

Step 1 - Download & install Node.js

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

Note: While installing Node.js, the Node Package Manager (NPM) will also be installed. NPM is the tool used to download and install the toxeus-node-sdk.

After installation, verify that you have Node.js and NPM installed by opening a terminal and running:

node -v && npm -v

You should see version numbers for both Node.js and NPM.

Step 2 - Create a new folder for your project

Create a folder for your Toxeus project and navigate into it. For example:

mkdir ToxeusProject
cd ToxeusProject
mkdir problems_and_solutions

Step 3 - Install the toxeus-node-sdk

Run the following commands from your project folder:

npm init -y
npm install toxeus-node-sdk@latest

Solve an example problem

With the toxeus-node-sdk installed, you now have access to a demo script included with the library.

Step 1 - Copy the demo script and .env file from the toxeus-node-sdk package

After installing the library, run the following commands:

cp node_modules/toxeus-node-sdk/demo/Toxeus_Cloud_Solver_demo.js .
cp node_modules/toxeus-node-sdk/demo/.env.example .env

These commands will copy Toxeus_Cloud_Solver_demo.js and a .env file template into your current working directory.

Step 2 - Edit the .env file to add your Toxeus credentials

Open the .env file in your favorite text editor:

TOXEUS_EMAIL=
TOXEUS_PASSWORD=

Fill in these values with the email and password you used when creating your Toxeus account. For example:

TOXEUS_EMAIL=jill@toxeus.org
TOXEUS_PASSWORD=MyPassword!

Save the .env file.

Step 3 - Review the demo script (optional)

Open Toxeus_Cloud_Solver_demo.js in a text editor if you’d like to review how the toxeus-node-sdk is being used. The script:

• Loads the .env file to read your credentials.
• Sets up a sample optimization problem.
• Calls the Toxeus Cloud Solver API to find a solution.
• Saves the solver results to JSON files in your working directory.

Toxeus_Cloud_Solver_demo.js (excerpt):

require('dotenv').config();

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

// Load your credentials from the environment variables defined in .env
const TOXEUS_EMAIL = process.env.TOXEUS_EMAIL;
const TOXEUS_PASSWORD = process.env.TOXEUS_PASSWORD;

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

// Example solver parameters and model setup...
model.setProblemName("Example Problem For The Toxeus Cloud Solver");
model.addConstraint("x + y + z <= 10");
model.setObjective({
  expression: "(1/x+y+z-3)^2+(x+1/y+z-3)^2+(x+y+1/z-3)^2",
  type: "minimize"
});

// Add decision variables and solver parameters as needed...
// ...

// Solve the model and save the results
toxeus.Solve(model);

Step 4 - Run the demo script

From your project directory, run:

node Toxeus_Cloud_Solver_demo.js

If successful, you should see JSON result files in your project directory after the solver completes. One file will contain the request details (request.default.json) and the other will contain the solver's response (response.default.json). For example:

ToxeusProject/
├── /problems_and_solutions
│   ├── request.default.json
│   ├── response.default.json
├── Toxeus_Cloud_Solver_demo.js
├── .env
├── node_modules
├── package.json

Where the problems_and_solutions folder will contain the request and response files containing the problem that was solved, and the solver's response which contains the solutions found:

Example request.default.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": 6,
   "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"
      }
   ],
   "algorithm_parameters": {
      "algorithm": "Nelder-Mead"
   },
   "penalized_points": [
      {
         "penalized_point": {
            "x": 0,
            "y": 0,
            "z": 0
         },
         "penalty_radius": 0.01
      }
   ]
}

Example response.default.json

{
    "solutions": [
        {
            "algorithm_parameters": {
                "algorithm": "Nelder-Mead"
            },
            "amount_of_constraint_violation": [
                0
            ],
            "max_error": 0,
            "number_of_algorithm_iterations": 1,
            "number_of_objective_function_evaluations_performed_during_optimization": 526,
            "number_of_solutions_found": 1,
            "objective_function_value": 10.122924981657516,
            "ran_out_of_time": false,
            "request_id_of_solver_that_found_solution": "70a852c2-11f7-433b-9875-d9c449054e33",
            "run_number": 1,
            "search_converged": true,
            "solution": [
                10.277791553958307,
                -0.13889583041818704,
                -0.13889572354763535
            ],
            "starting_point": [
                11.516810845870065,
                -3.166713283353195,
                4.8815237114199705
            ],
            "starting_point_number": "1:2",
            "time_spent_evaluating_objective_function_during_optimization": 5.280000000000064e-10,
            "time_spent_parsing_constraints": 0.000021,
            "time_spent_parsing_objective_function": 0.000002,
            "time_spent_solving": 0.001051,
            "total_error": 0
        },
        {
            "algorithm_parameters": {
                "algorithm": "Nelder-Mead"
            },
            "amount_of_constraint_violation": [
                0
            ],
            "max_error": 0,
            "number_of_algorithm_iterations": 1,
            "number_of_objective_function_evaluations_performed_during_optimization": 448,
            "number_of_solutions_found": 1,
            "objective_function_value": 10.122924981870606,
            "ran_out_of_time": false,
            "request_id_of_solver_that_found_solution": "70a852c2-11f7-433b-9875-d9c449054e33",
            "run_number": 1,
            "search_converged": true,
            "solution": [
                10.27779017231705,
                -0.13889483214280451,
                -0.13889534026486286
            ],
            "starting_point": [
                12.650298158379844,
                11.817643620098785,
                0.6883770606141625
            ],
            "starting_point_number": "1:5",
            "time_spent_evaluating_objective_function_during_optimization": 4.850000000000049e-10,
            "time_spent_parsing_constraints": 0.000019,
            "time_spent_parsing_objective_function": 0.000002,
            "time_spent_solving": 0.001027,
            "total_error": 0
        }
    ],
    "total_gigabyte_seconds_used_by_solver": 2.35,
    "total_gigabyte_seconds_charged_by_solver": 3,
    "solver_start_time": 1733731397.521,
    "time_of_request_completion": 1733731397.748
}

Congratulations! You have successfully:

• Created a Toxeus account.
• Installed Node.js and the toxeus-node-sdk.
• Copied and edited a demo script.
• Solved an example optimization problem using the Toxeus Cloud Solver.

You can now use this setup as a template for solving your own optimization problems or nonlinear systems with the Toxeus Cloud Solver. For more information about customizing solver parameters, adding decision variables, or working with constraints and objectives, please refer to the Toxeus Cloud Solver documentation.