wholecell-lens 0.0.26

No project description provided

Environment

Models of environments, which can be interfaced with cells via the agent module. Includes command line tools environment.boot for running environment and cell agents and environment.control for sending commands to agents.

Setup

See the top-level README.md for general setup instructions, and the actor/README.md for multi-agent simulation setup.

1. To run Whole Cell E.coli simulations, you need to have the sim_data files. You can generate them via the runFitter manual runscript. In the wcEcoli directory:

   > PYTHONPATH="$PWD" python runscripts/manual/runFitter.py

Zookeeper and Kafka

2. See actor/README.md for instructions to set up, start, and stop your Zookeeper and Kafka servers. To recap:

   1. Start Zookeeper in the directory where you untarred the Kafka and Zookeeper software:

      > bin/zookeeper-server-start.sh config/zookeeper.properties

   2. Then start the Kafka server in another shell tab in the same directory:

      > bin/kafka-server-start.sh config/server.properties --override listeners=PLAINTEXT://127.0.0.1:9092

3. Optional: Start the "Lens" environment visualization server and browser window per the instructions on the CovertLab/shepherd page. To recap:

   1. Run the Lens visualization server in the root directory of the CovertLab/shepherd repository:

      > lein run -m shepherd.lens

   2. Open a browser window onto http://localhost:33332

One Agent Per Terminal Tab (esp. for debugging)

Note: This section describes how to launch Environment and Cell agent processes directly from the command line. We usually use the "Agent Shepherd" approach described in the next section, but the direct approach lets you launch agents under a debugger. You can use it for one or more agents together with others running under a shepherd.

Tip: Run each process in a new terminal tab. Use iTerm split windows to make it easy to watch them all at once.

4. In the first terminal tab, launch an Environment agent:

   > python -m lens.environment.boot --type lattice --id lattice

   The Environment agent will wait for Cell simulation agents to register. You can optionally pass in a JSON --config '{...}' dictionary.

5. Now start a Cell agent in a new tab:

   > python -m lens.boot_compartment --outer-id lattice --type lookup --id 1

   Vary the agent type and other parameters as needed. Each agent needs an id that's unique among the currently running agents.

   You'll see messages like this one from the Cell agent to the Environment agent, declaring itself to the environment and giving its current state:

   <-- environment-receive (CELL_DECLARE) [1]: {"inner_id": "1", "agent_config": {...}, "state": {"volume": 1.2, "environment_change": {}}, "event": "CELL_DECLARE", "agent_id": "lattice"}

   In turn, the cell will receive messages like this:

   --> cell-receive (ENVIRONMENT_SYNCHRONIZE) [1]: {u'inner_id': u'1', u'state': {u'time': 0}, u'outer_id': u'lattice', u'event': u'ENVIRONMENT_SYNCHRONIZE'}

6. To debug an agent using the PyCharm debugger, first create a Run/Debug Configuration with the module name and parameters on the command lines above, e.g.

   Name: cell agent
   
   Module name: environment.boot
   Parameters: ecoli --id 40
   Python interpreter: Python 2.7 (wcEcoli2)
   Working directory: /Users/YOU/dev/wcEcoli
   ☑︎ Add content roots to PYTHONPATH
   ☑︎ Add source roots to PYTHONPATH
   ☑︎ Run with Python console
   

   Then set your breakpoints and invoke the Debug 'cell agent' menu command.

7. Start as many cells as desired, each with its own unique id agent name; each in a separate terminal tab or PyCharm run/debug tab.

8. Finally, use another terminal tab to start the simulation running:

   > python -m lens.environment.control run --id lattice

   You can pause and run it whenever you want.

9. To shut down the simulation, run shutdown in the command tab:

   > python -m lens.environment.control shutdown

Agent Shepherd

The usual way to start the simulation is to use the agent "Shepherd", which is a process that spawns agents in subprocesses (as requested via Kafka messages) so you don't have to launch each agent in its own terminal tab. Furthermore, this enables cell division wherein a cell agent process ends and two new ones begin. But to debug an agent, see the "One Agent Per Terminal Tab" instructions, above.

Clone the CovertLab/shepherd repo and run:

> lein run

Use a "Lens" browser page to view the agents in action. To do this, open another shell tab onto the shepherd repo directory and run:

> lein run -m shepherd.lens

then open a browser window onto http://localhost:33332/

Now you can start a virtual microscope experiment in a "command" terminal tab:

> python -m lens.environment.control experiment --number 3

This will send four ADD_AGENT messages to the shepherd: one for the lattice environment agent and three for the cell simulation agents. Note the agent_id for the lattice as you will need this for future control messages (like run and shutdown). These messages are received by the shepherd and you will see all the agents' logs in the "shepherd" tab.

You can run/pause the simulation at will:

> python -m lens.environment.control run

> python -m lens.environment.control pause

You can add another cell agent:

> python -m lens.environment.control add

(If you're running multiple environment agents, you can specify a lattice environment agent id via the --id option.)

You can remove a cell agent using the prefix of the agent's id (you don't have to type the whole id):

> python -m lens.environment.control remove --id dgaf

Finally, to shut down the experiment, run shutdown:

> python -m lens.environment.control shutdown

Notice this just shuts down the agents. The Shepherd is still running and ready for a new experiment. Use Ctrl-C to stop the Shepherd and Lens processes.

command summary

This is just a summary. Use the -h argument to get complete usage help on these command line programs.

The environment.boot commands run an agent in the current shell tab:

• ecoli - an ecoli cell agent
• lattice - a two dimensional lattice environment agent
• chemotaxis - a chemotaxis surrogate that can move up glucose gradients within a chemotaxis_experiment

The environment.control commands include:

• run - start/resume the simulation clock
• pause - pause the simulation clock
• shutdown - shutdown the simulation

Some environment.control commands require an agent shepherd, including:

• add - ask the shepherd to spawn an agent and add it to an environment
• remove - ask the shepherd to remove an agent
• experiment - ask the shepherd to spawn a lattice and multiple cell agents