laser-mind-client 0.1.1__tar.gz

laser_mind_client-0.1.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

laser_mind_client-0.1.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.1
+Name: laser-mind-client
+Version: 0.1.1
+Summary: A client python API for accessing LightSolver's capabilities
+Author-email: Assaf Kalinski <assaf@lightsolver.com>
+Project-URL: Homepage, https://lightsolver.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.5
+Requires-Dist: laser-mind-client-meta>=0.0.9
+Requires-Dist: ls_api_clients>=0.4.6
+Requires-Dist: ls-packers>=0.2.0
+
+
+## LightSolver Platform Client
+The LightSolver Platform Client is a Python package designed to interface with the LightSolver Cloud to facilitate solving Quadratic Unconstrained Binary Optimization (QUBO) problems.
+
+This package is designated for internal access to features during the development process, as well as serves as a prototype for future versions of the production LightSolver Platform Client.
+
+## Features
+- **QUBO Problem Solving:** The `solve_qubo` function accepts a QUBO problem, represented either as a 2D array (matrix) or an adjacency list, and returns the solution.
+- **Synchronous and Asynchronous Operation:** Users can choose between blocking (synchronous) and non-blocking (asynchronous) modes for QUBO problem solving.
+- **Flexible Installation:** Compatible with both Windows and Ubuntu systems.
+
+### Solve QUBO
+The `solve_qubo` function handles the computation of QUBO problems, either represented by a 2D array (matrix) or by an adjacency list. For code samples, see the **Usage** section.
+
+#### Input Matrix Validity
+- The matrix must be square.
+- The matrix supports int or float cell values.
+
+#### Return Value
+A dictionary with the following fields:
+```
+- 'id': Unique identifier of the solution.
+- 'solution': The solution as a Python list() of 1s and 0s.
+- 'objval: The objective value of the solution.
+- 'solverRunningTime': Time spent by the solver to calculate the problem.
+- 'receivedTime': Timestamp when the request was received by the server.
+```
+
+### Synchronous and Asynchronous Usage
+- **Synchronous Mode (Default):** The `waitForSolution` flag is set to **True** by default. The function blocks operations until a result is received.
+- **Asynchronous Mode:** Set `waitForSolution` to **False**. The function returns immediately with a token object, allowing the script to continue while the server processes the QUBO problem.
+
+## Setting Up
+
+### Prerequisites
+- Valid credentials for connecting to the LightSolver Cloud.
+- LightSolver Client code project - please use this link to download.
+- Python 3.10.
+- Operating System: Linux or Windows. Tested on Ubuntu 20.04 and Windows 11.
+- Highly Recommended: Use a virtual environment before installing laser-mind-client (Please see detailed action further below under the relevant OS).
+
+### Installation
+Complete the installation on Windows or Ubuntu as described below.
+For further assistance  with setup or connection issues, contact support@lightsolver.com.
+
+#### Windows
+1. Press the windows key, type "cmd", right click on the result and select "Run as administrator".
+2. Navigate to the root folder where you unzipped and plan to use the LightSolver Client:
+    ```
+    cd <your project folder>
+    ```
+
+3. (Recommended) Set the LightSolver credentials using environment variables (will remove the need to provide credentials for every usage).
+    Run the following command:
+```sh
+    python setup_env.py
+```
+
+4. (Recommended) Create a virtual environment:
+```sh
+    python -m venv .venv
+```
+
+5. (Recommended) Activate the new virtual environment:
+```sh
+    .venv\Scripts\activate
+```
+
+6. Install the laser-mind-client package. This command instructs pip to install the package from a local folder instead of searching online:
+```sh
+    pip install --no-cache-dir --find-links=.\packages laser-mind-client
+```
+
+7. (Recommended) Test LightSolver credentials
+    Run the following command:
+```sh
+    python test_env.py
+```
+    if test credentials failed , please  reinstall credentials using following commands:
+    - Exit virtual environment , by running :
+```sh
+    deactivate
+```
+    - Run the following command:
+```sh
+    python setup_env.py
+```
+
+
+#### Ubuntu
+1. Open new terminal window
+2. Navigate to the root folder where you unzipped and plan to use the LightSolver Client:
+    ```
+    cd <your project folder>
+    ```
+
+3. (Recommended) Set the LightSolver credentials using environment variables (will remove the need to provide credentials for every usage).
+    Run the following command:
+```sh
+    python3 setup_env.py
+    source ~/.bash_profile
+```
+
+4. (Recommended) Create a virtual environment:
+```sh
+    python3 -m venv .venv
+```
+
+5. (Recommended) Activate the new virtual environment:
+```sh
+    chmod 755  .venv/bin/activate
+    source .venv/bin/activate
+```
+
+6. Install the laser-mind-client package. This command instructs pip to install the package from a local folder instead of searching online:
+```sh
+    pip install --no-cache-dir --find-links=./packages laser-mind-client
+```
+
+7. (Recommended) Test LightSolver credentials
+    Run the following command:
+```sh
+    python3 test_env.py
+```
+    if test credentials failed , please  reinstall credentials using following commands:
+    - Exit virtual environment , by running :
+```sh
+    deactivate
+```
+    - Run the following command:
+```sh
+    python3 setup_env.py
+    source ~/.bash_profile
+```
+
+## Authentication
+Initialization of the `LaserMind` class automatically forms a secure and authenticated connection with the LightSolver Cloud.
+Subsequent calls by the same user are similarly secure and authenticated.
+
+## Usage
+To begin solving any QUBO problem:
+1. Create an instance of the ```LaserMind``` class. This class represents the client that requests solutions from the LightSolver Cloud.
+2. Call the ```solve_qubo``` function using either a matrix or an adjacency list.
+**Note:** You may either provide a value for ```matrixData``` or for ```edgeList```, but not both.
+
+### Solve QUBO Matrix Example
+This example creates a matrix representing a QUBO problem and solves it using the LightSolver Platform Client.
+The `solve_qubo` function is used with the following parameters:
+- ```matrixData```: A 2D array representing the QUBO problem.
+- ```timeout```: The required time limit for the calculation in seconds.
+
+```python
+import numpy
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboProblemData = numpy.random.randint(-1, 2, (10,10))
+
+# Symmetrize the matrix
+quboProblemData = (quboProblemData + quboProblemData.T) // 2
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+res = lsClient.solve_qubo(matrixData = quboProblemData, timeout=1)
+
+print(res)
+```
+
+### Solve QUBO Adjacency List Example
+This example describes a QUBO problem using an adjacency list. This is useful for sparse matrices.
+The `solve_qubo` function is used with the following parameters:
+- ```edgeList```: The adjacency list representing the QUBO problem.
+- ```timeout```: The required time limit for the calculation in seconds.
+
+
+```python
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboListData = [
+    [1,1,5],
+    [1,2,-6],
+    [2,2,3],
+    [2,3,-1],
+    [3,10,1]]
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+res = lsClient.solve_qubo(edgeList=quboListData, timeout=1)
+
+print(res)
+```
+
+### Solve QUBO Matrix using Asynchronous Flow
+This example demonstratse how to solve a QUBO problem asynchronously using the LightSolver Platform Client.
+Begin by creating a matrix to represent your QUBO problem.
+The `solve_qubo` function is used with the following parameters:
+   - `matrixData`: A 2D array representing the QUBO problem.
+   - `timeout`: The desired time limit for the calculation in seconds.
+   - `waitForSolution`: A boolean flag set to `False` to indicate non-blocking mode.
+
+```python
+import numpy
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboProblemData = numpy.random.randint(-1, 2, (10,10))
+
+# Symmetrize our matrix
+quboProblemData = (quboProblemData + quboProblemData.T) // 2
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+# Request a solution to the QUBO problem and get the request token for future retrieval.
+# This call does not block operations until the problem is solved.
+requestToken = lsClient.solve_qubo(matrixData = quboProblemData, timeout=1, waitForSolution=False)
+
+# You can run other code here that is not dependant on the request, while the server processes your request.
+
+# Retrieve the solution using the get_solution_sync method.
+# This blocks operations until the solution is acquired.
+res = lsClient.get_solution_sync(requestToken)
+
+print(res)
+```

laser_mind_client-0.1.1/README.md

@@ -0,0 +1,228 @@
+
+## LightSolver Platform Client
+The LightSolver Platform Client is a Python package designed to interface with the LightSolver Cloud to facilitate solving Quadratic Unconstrained Binary Optimization (QUBO) problems.
+
+This package is designated for internal access to features during the development process, as well as serves as a prototype for future versions of the production LightSolver Platform Client.
+
+## Features
+- **QUBO Problem Solving:** The `solve_qubo` function accepts a QUBO problem, represented either as a 2D array (matrix) or an adjacency list, and returns the solution.
+- **Synchronous and Asynchronous Operation:** Users can choose between blocking (synchronous) and non-blocking (asynchronous) modes for QUBO problem solving.
+- **Flexible Installation:** Compatible with both Windows and Ubuntu systems.
+
+### Solve QUBO
+The `solve_qubo` function handles the computation of QUBO problems, either represented by a 2D array (matrix) or by an adjacency list. For code samples, see the **Usage** section.
+
+#### Input Matrix Validity
+- The matrix must be square.
+- The matrix supports int or float cell values.
+
+#### Return Value
+A dictionary with the following fields:
+```
+- 'id': Unique identifier of the solution.
+- 'solution': The solution as a Python list() of 1s and 0s.
+- 'objval: The objective value of the solution.
+- 'solverRunningTime': Time spent by the solver to calculate the problem.
+- 'receivedTime': Timestamp when the request was received by the server.
+```
+
+### Synchronous and Asynchronous Usage
+- **Synchronous Mode (Default):** The `waitForSolution` flag is set to **True** by default. The function blocks operations until a result is received.
+- **Asynchronous Mode:** Set `waitForSolution` to **False**. The function returns immediately with a token object, allowing the script to continue while the server processes the QUBO problem.
+
+## Setting Up
+
+### Prerequisites
+- Valid credentials for connecting to the LightSolver Cloud.
+- LightSolver Client code project - please use this link to download.
+- Python 3.10.
+- Operating System: Linux or Windows. Tested on Ubuntu 20.04 and Windows 11.
+- Highly Recommended: Use a virtual environment before installing laser-mind-client (Please see detailed action further below under the relevant OS).
+
+### Installation
+Complete the installation on Windows or Ubuntu as described below.
+For further assistance  with setup or connection issues, contact support@lightsolver.com.
+
+#### Windows
+1. Press the windows key, type "cmd", right click on the result and select "Run as administrator".
+2. Navigate to the root folder where you unzipped and plan to use the LightSolver Client:
+    ```
+    cd <your project folder>
+    ```
+
+3. (Recommended) Set the LightSolver credentials using environment variables (will remove the need to provide credentials for every usage).
+    Run the following command:
+```sh
+    python setup_env.py
+```
+
+4. (Recommended) Create a virtual environment:
+```sh
+    python -m venv .venv
+```
+
+5. (Recommended) Activate the new virtual environment:
+```sh
+    .venv\Scripts\activate
+```
+
+6. Install the laser-mind-client package. This command instructs pip to install the package from a local folder instead of searching online:
+```sh
+    pip install --no-cache-dir --find-links=.\packages laser-mind-client
+```
+
+7. (Recommended) Test LightSolver credentials
+    Run the following command:
+```sh
+    python test_env.py
+```
+    if test credentials failed , please  reinstall credentials using following commands:
+    - Exit virtual environment , by running :
+```sh
+    deactivate
+```
+    - Run the following command:
+```sh
+    python setup_env.py
+```
+
+
+#### Ubuntu
+1. Open new terminal window
+2. Navigate to the root folder where you unzipped and plan to use the LightSolver Client:
+    ```
+    cd <your project folder>
+    ```
+
+3. (Recommended) Set the LightSolver credentials using environment variables (will remove the need to provide credentials for every usage).
+    Run the following command:
+```sh
+    python3 setup_env.py
+    source ~/.bash_profile
+```
+
+4. (Recommended) Create a virtual environment:
+```sh
+    python3 -m venv .venv
+```
+
+5. (Recommended) Activate the new virtual environment:
+```sh
+    chmod 755  .venv/bin/activate
+    source .venv/bin/activate
+```
+
+6. Install the laser-mind-client package. This command instructs pip to install the package from a local folder instead of searching online:
+```sh
+    pip install --no-cache-dir --find-links=./packages laser-mind-client
+```
+
+7. (Recommended) Test LightSolver credentials
+    Run the following command:
+```sh
+    python3 test_env.py
+```
+    if test credentials failed , please  reinstall credentials using following commands:
+    - Exit virtual environment , by running :
+```sh
+    deactivate
+```
+    - Run the following command:
+```sh
+    python3 setup_env.py
+    source ~/.bash_profile
+```
+
+## Authentication
+Initialization of the `LaserMind` class automatically forms a secure and authenticated connection with the LightSolver Cloud.
+Subsequent calls by the same user are similarly secure and authenticated.
+
+## Usage
+To begin solving any QUBO problem:
+1. Create an instance of the ```LaserMind``` class. This class represents the client that requests solutions from the LightSolver Cloud.
+2. Call the ```solve_qubo``` function using either a matrix or an adjacency list.
+**Note:** You may either provide a value for ```matrixData``` or for ```edgeList```, but not both.
+
+### Solve QUBO Matrix Example
+This example creates a matrix representing a QUBO problem and solves it using the LightSolver Platform Client.
+The `solve_qubo` function is used with the following parameters:
+- ```matrixData```: A 2D array representing the QUBO problem.
+- ```timeout```: The required time limit for the calculation in seconds.
+
+```python
+import numpy
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboProblemData = numpy.random.randint(-1, 2, (10,10))
+
+# Symmetrize the matrix
+quboProblemData = (quboProblemData + quboProblemData.T) // 2
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+res = lsClient.solve_qubo(matrixData = quboProblemData, timeout=1)
+
+print(res)
+```
+
+### Solve QUBO Adjacency List Example
+This example describes a QUBO problem using an adjacency list. This is useful for sparse matrices.
+The `solve_qubo` function is used with the following parameters:
+- ```edgeList```: The adjacency list representing the QUBO problem.
+- ```timeout```: The required time limit for the calculation in seconds.
+
+
+```python
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboListData = [
+    [1,1,5],
+    [1,2,-6],
+    [2,2,3],
+    [2,3,-1],
+    [3,10,1]]
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+res = lsClient.solve_qubo(edgeList=quboListData, timeout=1)
+
+print(res)
+```
+
+### Solve QUBO Matrix using Asynchronous Flow
+This example demonstratse how to solve a QUBO problem asynchronously using the LightSolver Platform Client.
+Begin by creating a matrix to represent your QUBO problem.
+The `solve_qubo` function is used with the following parameters:
+   - `matrixData`: A 2D array representing the QUBO problem.
+   - `timeout`: The desired time limit for the calculation in seconds.
+   - `waitForSolution`: A boolean flag set to `False` to indicate non-blocking mode.
+
+```python
+import numpy
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboProblemData = numpy.random.randint(-1, 2, (10,10))
+
+# Symmetrize our matrix
+quboProblemData = (quboProblemData + quboProblemData.T) // 2
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+# Request a solution to the QUBO problem and get the request token for future retrieval.
+# This call does not block operations until the problem is solved.
+requestToken = lsClient.solve_qubo(matrixData = quboProblemData, timeout=1, waitForSolution=False)
+
+# You can run other code here that is not dependant on the request, while the server processes your request.
+
+# Retrieve the solution using the get_solution_sync method.
+# This blocks operations until the solution is acquired.
+res = lsClient.get_solution_sync(requestToken)
+
+print(res)
+```

laser_mind_client-0.1.1/laser_mind_client/__init__.py

@@ -0,0 +1 @@
+from laser_mind_client.laser_mind_client import LaserMind

laser_mind_client-0.1.1/laser_mind_client/laser_mind_client.py

@@ -0,0 +1,170 @@
+import os
+import logging
+import time
+import numpy
+
+from ls_api_clients import LSAPIClient
+from ls_packers import float_array_as_int
+from ls_packers import numpy_array_to_triu_flat
+from laser_mind_client_meta import MessageKeys
+
+logging.basicConfig(
+    filename="laser-mind.log",
+    level=logging.INFO,
+    format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %H:%M:%S')
+
+def symmetrize(matrix):
+        """
+        Symmetrizes a given matrix in numpy array form
+        """
+        if (matrix == matrix.T).all():
+        # do nothing if the matrix is already symmetric
+            return matrix
+        result = (matrix + matrix.T) * 0.5
+        return result
+
+class LaserMind:
+    """
+    ## A client for accessing LightSolver's computaion capabilities via web services.
+    """
+    POLL_MAX_RETRIES = 100000
+    POLL_DELAY_SECS = 0.5
+
+    def __init__(self,
+                 username = None,
+                 password = None,
+                 states_per_call=3):
+        if username == None:
+            if 'LS_USER' in os.environ:
+                username = os.environ['LS_USER']
+            else:
+                raise Exception("the 'username' parameter cannot be None if the LS_USER environment variable is not set.")
+        if password == None:
+            if 'LS_PASS' in os.environ:
+                password = os.environ['LS_PASS']
+            else:
+                raise Exception("the 'password' parameter cannot be None if the LS_PASS environment variable is not set.")
+
+        self.states_per_call = states_per_call
+        logging.info('LightSolver connection init started')
+        self.apiClient = LSAPIClient(username, password)
+        logging.info('LightSolver connection init finished')
+
+    def get_solution_by_id(self, solutionId, timestamp):
+        """
+        Retrieve a previously requested solution from the LightSolver cloud.
+
+        - `solutionId` : the solution id received when requesting a solution.
+        - `timestamp` : the timestamp received when requesting a solution.
+        """
+        result = self.apiClient.SendResultRequest(solutionId, timestamp)
+        return result
+
+    def get_solution_sync(self, requestInfo):
+        """
+        Waits for a solution to be available and downloads it.
+
+        - `requestInfo` : a dictionary containing 'id' and 'reqTime' keys needed for retrieving the solution.
+        """
+        for try_num in range(1, self.POLL_MAX_RETRIES):
+            result = self.get_solution_by_id(requestInfo['id'], requestInfo['reqTime'])
+            if result != None:
+                result["receivedTime"] = requestInfo["receivedTime"]
+                logging.info(f"got solution for {requestInfo}, try #{try_num}")
+                return result
+            time.sleep((self.POLL_DELAY_SECS))
+
+        logging.warning(f"got timeout for {requestInfo}")
+        raise FileNotFoundError(f"Exceeded max retries when attempting to find {requestInfo['id']}")
+
+    def make_command_input(self, matrixData = None, edgeList = None, timeout = 10):
+        """
+        Creates the message payload for a request input.
+        """
+        commandInput = {}
+
+        if matrixData is not None:
+            varCount = len(matrixData)
+            if varCount > 10000 or varCount < 10:
+                raise(ValueError("The total number of variables must be between 10-10000"))
+            if type(matrixData) == numpy.ndarray:
+                matrixData = symmetrize(matrixData)
+                if matrixData.dtype == numpy.float32 or matrixData.dtype == numpy.float64:
+                    triuFlat = float_array_as_int(numpy_array_to_triu_flat(matrixData))
+                    commandInput[MessageKeys.FLOAT_DATA_AS_INT] = True
+                else:
+                    triuFlat = numpy_array_to_triu_flat(matrixData)
+            else:
+                validationArr = [len(matrixData[i]) != varCount for i in range(varCount)]
+                if numpy.array(validationArr).any():
+                    raise(ValueError("The input must be a square matrix"))
+                triuFlat = numpy_array_to_triu_flat(symmetrize(numpy.array(matrixData)))
+            commandInput[MessageKeys.QUBO_MATRIX] = triuFlat.tolist()
+        elif edgeList is not None:
+            if type(edgeList) == numpy.ndarray:
+                varCount = numpy.max(edgeList[:,0:2])
+                edgeList = edgeList.tolist()
+            else:
+                varCount = numpy.max(numpy.array(edgeList)[:,0:2])
+            if varCount > 10000 or varCount < 10:
+                raise(ValueError("The total number of variables must be between 10-10000"))
+            commandInput[MessageKeys.QUBO_EDGE_LIST] = edgeList
+        else:
+            raise Exception("You must provide either a QUBO matrix or a QUBO edge list")
+
+        commandInput[MessageKeys.ALGO_RUN_TIMEOUT] = timeout
+        return commandInput, int(varCount)
+
+    def upload_qubo_input(self, matrixData = None, edgeList = None, timeout = 10, inputPath = None):
+        """
+        Uploads the given input to the lightsolver cloud for later processing.
+
+        - `matrixData` : (optional) The matrix data of the target problem, must be a symmetric matrix. if given, the edge list in the vortex parameters is ignored.
+        - `edgeList` : (optional) The edge list describing Ising matrix of the target problem. if the matrixData parameter is given, this parameter is ignored.
+        - `timeout` : (optional) the running timeout, in seconds for the algorithm, must be in the range 0.001 - 60 (default: 10).
+        - `inputPath` : (optional) The the path to a pre-uploaded input file if not given a random string is used returned.
+
+        Returns a dictionary with the 'data' key being a dictionary representing the solution using the following keys:
+        - `iid` : The id of the uploaded file.
+        - `varCount` : The amount number of variables of the problem.
+
+        """
+        commandInput, varCount = self.make_command_input(matrixData, edgeList, timeout)
+
+        iid = self.apiClient.upload_command_input(commandInput, inputPath)
+        return iid, varCount
+
+    def solve_qubo(self, matrixData = None, edgeList = None, inputPath = None, timeout = 10, waitForSolution = True):
+        """
+        Solves a qubo problem using the optimized algorithm.
+
+        - `matrixData` : (optional) The matrix data of the target problem, must be a symmetric matrix. if given, the edge list in the vortex parameters is ignored.
+        - `edgeList` : (optional) The edge list describing Ising matrix of the target problem. if the matrixData parameter is given, this parameter is ignored.
+        - `inputPath` : (optional) The the path to a pre-uploaded input file, the upload can be done using the upload_qubo_input() method of this class.
+        - `timeout` : (optional) the running timeout, in seconds for the algorithm, must be in the range 0.001 - 60 (default: 10).
+        - `waitForSolution` : (optional) When set to True it waits for the solution, else returns with retrieval info (default: True).
+
+        Returns a dictionary with the 'data' key being a dictionary representing the solution using the following keys:
+        - `objval` : The objective value.
+        - `solution` : The optimal solution found.
+        """
+        command_name = MessageKeys.QUBO_COMMAND_NAME
+        if inputPath == None:
+            iid, varCount = self.upload_qubo_input(matrixData, edgeList, timeout)
+        else:
+            iid = inputPath
+            varCount = 10000
+
+        requestInput = {
+            MessageKeys.QUBO_INPUT_PATH : iid,
+            MessageKeys.ALGO_RUN_TIMEOUT : timeout,
+            MessageKeys.VAR_COUNT_KEY : varCount
+            }
+
+        response = self.apiClient.SendCommandRequest(command_name, requestInput)
+        logging.info(f"got response {response}")
+        if not waitForSolution:
+            return response
+        result = self.get_solution_sync(response)
+        return result
+

laser_mind_client-0.1.1/laser_mind_client.egg-info/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.1
+Name: laser-mind-client
+Version: 0.1.1
+Summary: A client python API for accessing LightSolver's capabilities
+Author-email: Assaf Kalinski <assaf@lightsolver.com>
+Project-URL: Homepage, https://lightsolver.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.5
+Requires-Dist: laser-mind-client-meta>=0.0.9
+Requires-Dist: ls_api_clients>=0.4.6
+Requires-Dist: ls-packers>=0.2.0
+
+
+## LightSolver Platform Client
+The LightSolver Platform Client is a Python package designed to interface with the LightSolver Cloud to facilitate solving Quadratic Unconstrained Binary Optimization (QUBO) problems.
+
+This package is designated for internal access to features during the development process, as well as serves as a prototype for future versions of the production LightSolver Platform Client.
+
+## Features
+- **QUBO Problem Solving:** The `solve_qubo` function accepts a QUBO problem, represented either as a 2D array (matrix) or an adjacency list, and returns the solution.
+- **Synchronous and Asynchronous Operation:** Users can choose between blocking (synchronous) and non-blocking (asynchronous) modes for QUBO problem solving.
+- **Flexible Installation:** Compatible with both Windows and Ubuntu systems.
+
+### Solve QUBO
+The `solve_qubo` function handles the computation of QUBO problems, either represented by a 2D array (matrix) or by an adjacency list. For code samples, see the **Usage** section.
+
+#### Input Matrix Validity
+- The matrix must be square.
+- The matrix supports int or float cell values.
+
+#### Return Value
+A dictionary with the following fields:
+```
+- 'id': Unique identifier of the solution.
+- 'solution': The solution as a Python list() of 1s and 0s.
+- 'objval: The objective value of the solution.
+- 'solverRunningTime': Time spent by the solver to calculate the problem.
+- 'receivedTime': Timestamp when the request was received by the server.
+```
+
+### Synchronous and Asynchronous Usage
+- **Synchronous Mode (Default):** The `waitForSolution` flag is set to **True** by default. The function blocks operations until a result is received.
+- **Asynchronous Mode:** Set `waitForSolution` to **False**. The function returns immediately with a token object, allowing the script to continue while the server processes the QUBO problem.
+
+## Setting Up
+
+### Prerequisites
+- Valid credentials for connecting to the LightSolver Cloud.
+- LightSolver Client code project - please use this link to download.
+- Python 3.10.
+- Operating System: Linux or Windows. Tested on Ubuntu 20.04 and Windows 11.
+- Highly Recommended: Use a virtual environment before installing laser-mind-client (Please see detailed action further below under the relevant OS).
+
+### Installation
+Complete the installation on Windows or Ubuntu as described below.
+For further assistance  with setup or connection issues, contact support@lightsolver.com.
+
+#### Windows
+1. Press the windows key, type "cmd", right click on the result and select "Run as administrator".
+2. Navigate to the root folder where you unzipped and plan to use the LightSolver Client:
+    ```
+    cd <your project folder>
+    ```
+
+3. (Recommended) Set the LightSolver credentials using environment variables (will remove the need to provide credentials for every usage).
+    Run the following command:
+```sh
+    python setup_env.py
+```
+
+4. (Recommended) Create a virtual environment:
+```sh
+    python -m venv .venv
+```
+
+5. (Recommended) Activate the new virtual environment:
+```sh
+    .venv\Scripts\activate
+```
+
+6. Install the laser-mind-client package. This command instructs pip to install the package from a local folder instead of searching online:
+```sh
+    pip install --no-cache-dir --find-links=.\packages laser-mind-client
+```
+
+7. (Recommended) Test LightSolver credentials
+    Run the following command:
+```sh
+    python test_env.py
+```
+    if test credentials failed , please  reinstall credentials using following commands:
+    - Exit virtual environment , by running :
+```sh
+    deactivate
+```
+    - Run the following command:
+```sh
+    python setup_env.py
+```
+
+
+#### Ubuntu
+1. Open new terminal window
+2. Navigate to the root folder where you unzipped and plan to use the LightSolver Client:
+    ```
+    cd <your project folder>
+    ```
+
+3. (Recommended) Set the LightSolver credentials using environment variables (will remove the need to provide credentials for every usage).
+    Run the following command:
+```sh
+    python3 setup_env.py
+    source ~/.bash_profile
+```
+
+4. (Recommended) Create a virtual environment:
+```sh
+    python3 -m venv .venv
+```
+
+5. (Recommended) Activate the new virtual environment:
+```sh
+    chmod 755  .venv/bin/activate
+    source .venv/bin/activate
+```
+
+6. Install the laser-mind-client package. This command instructs pip to install the package from a local folder instead of searching online:
+```sh
+    pip install --no-cache-dir --find-links=./packages laser-mind-client
+```
+
+7. (Recommended) Test LightSolver credentials
+    Run the following command:
+```sh
+    python3 test_env.py
+```
+    if test credentials failed , please  reinstall credentials using following commands:
+    - Exit virtual environment , by running :
+```sh
+    deactivate
+```
+    - Run the following command:
+```sh
+    python3 setup_env.py
+    source ~/.bash_profile
+```
+
+## Authentication
+Initialization of the `LaserMind` class automatically forms a secure and authenticated connection with the LightSolver Cloud.
+Subsequent calls by the same user are similarly secure and authenticated.
+
+## Usage
+To begin solving any QUBO problem:
+1. Create an instance of the ```LaserMind``` class. This class represents the client that requests solutions from the LightSolver Cloud.
+2. Call the ```solve_qubo``` function using either a matrix or an adjacency list.
+**Note:** You may either provide a value for ```matrixData``` or for ```edgeList```, but not both.
+
+### Solve QUBO Matrix Example
+This example creates a matrix representing a QUBO problem and solves it using the LightSolver Platform Client.
+The `solve_qubo` function is used with the following parameters:
+- ```matrixData```: A 2D array representing the QUBO problem.
+- ```timeout```: The required time limit for the calculation in seconds.
+
+```python
+import numpy
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboProblemData = numpy.random.randint(-1, 2, (10,10))
+
+# Symmetrize the matrix
+quboProblemData = (quboProblemData + quboProblemData.T) // 2
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+res = lsClient.solve_qubo(matrixData = quboProblemData, timeout=1)
+
+print(res)
+```
+
+### Solve QUBO Adjacency List Example
+This example describes a QUBO problem using an adjacency list. This is useful for sparse matrices.
+The `solve_qubo` function is used with the following parameters:
+- ```edgeList```: The adjacency list representing the QUBO problem.
+- ```timeout```: The required time limit for the calculation in seconds.
+
+
+```python
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboListData = [
+    [1,1,5],
+    [1,2,-6],
+    [2,2,3],
+    [2,3,-1],
+    [3,10,1]]
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+res = lsClient.solve_qubo(edgeList=quboListData, timeout=1)
+
+print(res)
+```
+
+### Solve QUBO Matrix using Asynchronous Flow
+This example demonstratse how to solve a QUBO problem asynchronously using the LightSolver Platform Client.
+Begin by creating a matrix to represent your QUBO problem.
+The `solve_qubo` function is used with the following parameters:
+   - `matrixData`: A 2D array representing the QUBO problem.
+   - `timeout`: The desired time limit for the calculation in seconds.
+   - `waitForSolution`: A boolean flag set to `False` to indicate non-blocking mode.
+
+```python
+import numpy
+from laser_mind_client import LaserMind
+
+# Create a mock QUBO problem
+quboProblemData = numpy.random.randint(-1, 2, (10,10))
+
+# Symmetrize our matrix
+quboProblemData = (quboProblemData + quboProblemData.T) // 2
+
+# Connect to the LightSolver Cloud
+lsClient = LaserMind()
+
+# Request a solution to the QUBO problem and get the request token for future retrieval.
+# This call does not block operations until the problem is solved.
+requestToken = lsClient.solve_qubo(matrixData = quboProblemData, timeout=1, waitForSolution=False)
+
+# You can run other code here that is not dependant on the request, while the server processes your request.
+
+# Retrieve the solution using the get_solution_sync method.
+# This blocks operations until the solution is acquired.
+res = lsClient.get_solution_sync(requestToken)
+
+print(res)
+```

laser_mind_client-0.1.1/laser_mind_client.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+laser_mind_client/__init__.py
+laser_mind_client/laser_mind_client.py
+laser_mind_client.egg-info/PKG-INFO
+laser_mind_client.egg-info/SOURCES.txt
+laser_mind_client.egg-info/dependency_links.txt
+laser_mind_client.egg-info/requires.txt
+laser_mind_client.egg-info/top_level.txt

laser_mind_client-0.1.1/laser_mind_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

laser_mind_client-0.1.1/laser_mind_client.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.21.5
+laser-mind-client-meta>=0.0.9
+ls_api_clients>=0.4.6
+ls-packers>=0.2.0

laser_mind_client-0.1.1/laser_mind_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+laser_mind_client

laser_mind_client-0.1.1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "laser-mind-client"
+version = "0.1.1"
+authors = [
+  { name="Assaf Kalinski", email="assaf@lightsolver.com" },
+]
+description = "A client python API for accessing LightSolver's capabilities"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+  'numpy>=1.21.5',
+  'laser-mind-client-meta>=0.0.9',
+  'ls_api_clients>=0.4.6',
+  'ls-packers>=0.2.0'
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Homepage" = "https://lightsolver.com"
+
+
+[tool.setuptools.packages.find]
+include = ["laser_mind_client"]
+

laser_mind_client-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+