Package: wholecell-lens
EnvironmentModels of environments, which can be interfaced with cells via the agent module.
Includes command line toolsenvironment.bootfor running environment and cell agents
andenvironment.controlfor sending commands to agents.SetupSee the top-levelREADME.mdfor general setup instructions, and theactor/README.mdfor multi-agent simulation setup.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.pyZookeeper and KafkaSeeactor/README.mdfor instructions to set up, start, and stop your Zookeeper and Kafka servers. To recap:Start Zookeeper in the directory where you untarred the Kafka and Zookeeper software:> bin/zookeeper-server-start.sh config/zookeeper.propertiesThen 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:9092Optional:Start the "Lens" environment visualization server and browser window per the instructions on theCovertLab/shepherdpage. To recap:Run the Lens visualization server in the root directory of theCovertLab/shepherdrepository:> lein run -m shepherd.lensOpen a browser window ontohttp://localhost:33332One 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.In the first terminal tab, launch an Environment agent:> python -m lens.environment.boot --type lattice --id latticeThe Environment agent will wait for Cell simulation agents to register.
You can optionally pass in a JSON--config '{...}'dictionary.Now start a Cell agent in a new tab:> python -m lens.environment.boot --outer-id lattice --type lookup --id 1Vary the agent type and other parameters as needed. Each agent needs anidthat'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'}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 consoleThen set your breakpoints and invoke theDebug 'cell agent'menu command.Start as many cells as desired, each with its own uniqueidagent name; each in a
separate terminal tab or PyCharm run/debug tab.Finally, use another terminal tab to start the simulation running:> python -m lens.environment.control run --id latticeYou canpauseandrunit whenever you want.To shut down the simulation, runshutdownin the command tab:> python -m lens.environment.control shutdownAgent ShepherdThe 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 theCovertLab/shepherdrepo and run:> lein runUse 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.lensthen open a browser window ontohttp://localhost:33332/Now you can start a virtual microscope experiment in a "command" terminal tab:> python -m lens.environment.control experiment --number 3 --type metabolism --experiment_id exp123This will send fourADD_AGENTmessages to the shepherd: one for thelattice environmentagent and three for thecell simulationagents. Note theagent_idfor the lattice as you will need this for future control messages (likerunandshutdown). These messages are received by the shepherd and you will see all the agents' logs in the "shepherd" tab.You canrun/pausethe simulation at will:> python -m lens.environment.control run> python -m lens.environment.control pauseYou 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--idoption.)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 dgafFinally, to shut down the experiment, runshutdown:> python -m lens.environment.control shutdownNotice this just shuts down the agents. The Shepherd is still running and ready for a new experiment.
UseCtrl-Cto stop the Shepherd and Lens processes.command summaryThis is just a summary.
Use the-hargument 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 agentlattice - a two dimensional lattice environment agentchemotaxis - a chemotaxis surrogate that can move up glucose gradients within a chemotaxis_experimentThe environment.control commands include:run - start/resume the simulation clockpause - pause the simulation clockshutdown - shutdown the simulationSome environment.control commands require anagent shepherd, including:add - ask the shepherd to spawn an agent and add it to an environmentremove - ask the shepherd to remove an agentexperiment - ask the shepherd to spawn a lattice and multiple cell agents