Docs/readme

README.md

@@ -1,83 +1,90 @@
-## Installation
+# StochSS-Compute
 
-#### Docker
-
-The easiest way to get stochss-compute running is with docker. Clone the repository and run the following in the root directory:
+With StochSS-Compute, you can run GillesPy2 simulations on your own server. Results are cached and anonymized, so you
+can easily save and recall previous simulations. 
 
+## Example Quick Start
+First, clone the repository.
 ```
-docker-compose up --build
+git clone https://github.com/StochSS/stochss-compute.git
+cd stochss-compute
 ```
-#### Minikube
-- first requires `minikube`, `docker`, and `kubectl` to be installed. Then:
+- If you are unfamiliar with python virtual environments, read this [documentation](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) first.
+- Note that you will have to activate your venv every time you run stochSS-compute, as well as for your dask scheduler and each of its workers.
+- The following will set up the `dask-scheduler`, one `dask-worker`, the backend api server, and launch an example `jupyter` notebook.
+- Each of these must be run in separate terminal windows in the main `stochss-compute` directory.
+- Just copy and paste!
 ```
-minikube start
-cd into kubernetes directory
-kubectl apply -f api_deployment.yaml
-minikube dashboard
+# Terminal 1
+python3 -m venv venv
+source venv/bin/activate
+pip3 install -r requirements.txt
+dask-scheduler
 ```
-- Now, wait for the stochss-compute container to be created.
-
-From here, there are two ways to access the cluster.
-
-##### To set up local access:
-`minikube service --url stochss-compute-service`
-- exposes external IP (on EKS or otherwise this is handled by your cloud provider)
-- use this host and IP when calling ComputeServer()
-- first time will be slow because the dask containers have to start up
-
-##### To use ngrok to set up public access  (ngrok.com to sign up for a free account and download/install):
 ```
-url=$(minikube service --url stochss-compute-service)
-ngrok http $url
+# Terminal 2
+source venv/bin/activate
+dask-worker localhost:8786
 ```
-- use this URL when calling ComputeServer()
-
-#### Manually
-
-Ensure that the following dependencies are installed with your package manager of choice:
-
-- `python-poetry`
-- `redis`
-
-Clone the repository and navigate into the new `stochss-compute` directory. Once inside, execute the following command to install the Python dependencies:
-
 ```
-poetry install
+# Terminal 3
+source venv/bin/activate
+python3 app.py
 ```
-
-And to activate the new virtual environment:
+- Stochss-compute is now running on localhost:1234.
+<!-- - Dask compute cluster configuration parameters can be passed to `app.py`, see the [documentation](https://github.com/StochSS/stochss-compute/blob/dev/stochss_compute/api/delegate/dask_delegate.py#L20). -->
 
 ```
-poetry shell
+# Terminal 4
+source venv/bin/activate
+jupyter notebook --port=9999
 ```
+- This notebook will show you how to use StochSS-compute.
+- Jupyter should then launch automatically, where you can then navigate to the examples directory and open up StartHere.ipynb.
+- If not, copy and paste the following URL into your web browser:  
+`http://localhost:9999/notebooks/examples/StartHere.ipynb`
+#### Docker
 
-Once complete, both `celery` and `redis` need to be running.
-
-```
-celery -A stochss_compute.api worker -l INFO
-```
+An alternative installation to the above method is to use docker. We host an image on docker hub you can download and use simply by running the following line.
 
-`redis` can be run in several ways. If you prefer a `systemd` daemon:
 
 ```
-sudo systemctl start redis
+docker run -p 1234:1234 mdip226/stochss-compute:latest
 ```
 
-Otherwise:
+- The `-p` flag publishes the container's exposed port on the host computer, as in `-p <hostPort>:<containerPort>`
+- Stochss-compute is now running on localhost:1234.
 
+<!-- #### Minikube
+- A third usage of StochSS compute it to use it with "Minikube", which is part of [Kubernetes](https://kubernetes.io/).
+- Requires `minikube`, `docker`, and `kubectl` to be installed. Then:
 ```
-redis-server
+minikube start
+cd into kubernetes directory
+kubectl apply -f api_deployment.yaml
+minikube dashboard
 ```
+- Now, wait for the stochss-compute container to be created.
 
-Finally, start the stochss-compute server.
+- From here, there are two ways to access the cluster. -->
 
+<!-- ##### To set up local access:
+`minikube service --url stochss-compute-service`
+- exposes external IP (on EKS or otherwise this is handled by your cloud provider)
+- use this host and IP when calling ComputeServer()
+- first time will be slow because the dask containers have to start up
+
+##### To use ngrok to set up public access  (ngrok.com to sign up for a free account and download/install):
 ```
-poetry run stochss-compute
+url=$(minikube service --url stochss-compute-service)
+ngrok http $url
 ```
+- use this URL when calling ComputeServer() -->
+
 
-## Usage
+<!-- ## Usage
 
-Simulations are run on stochss-compute via Jupyter notebooks.
+- The easiest way to run stochss-compute simulations is via Jupyter notebooks:
 
 ```python
 import numpy, gillespy2
@@ -118,9 +125,13 @@ class ToggleSwitch(gillespy2.Model):
 # Instantiate a new instance of the model.
 model = ToggleSwitch()
 
-# Run the model on a stochss-compute server instance running on localhost.
-results = RemoteSimulation.on(ComputeServer("127.0.0.1", port=1234).with_model(model).run()
+# Run the model on a stochss-compute server instance running on localhost. 
+# The default port is 1234, but will depend on how you choose to set it up.
+results = RemoteSimulation.on(ComputeServer("127.0.0.1", port=1234)).with_model(model).run()
+
+# Wait for the simulation to finish.
+results.wait()
 
 # Plot the results.
 results.plot()
-```
+``` -->

stochss_compute/remote_results.py

@@ -156,5 +156,9 @@ def resolve(self) -> Results:
         return results
 
     def cancel(self):
+        """
+        Cancels the remote job.
+        """
+# TODO
         stop_response = self.server.post(Endpoint.JOB, f"/{self.result_id}/stop")