edu.columbia.cs.coms4701.agent
Interface Environment<K extends AgentAction,P extends AgentPercept,A extends Agent<K,P>>

All Known Subinterfaces:
GridEnvironment<K,P,A>
All Known Implementing Classes:
AbstractEnvironment, AbstractGridEnvironment, PenteEnvironment, RoombaEnvironment

public interface Environment<K extends AgentAction,P extends AgentPercept,A extends Agent<K,P>>

An environment in which one more agents act.

Note that an environment is parameterized on the particular type of agent it supports. This enables particular implementations to make richer assumptions about the capabilities of agents.

An environment should support the following general model:

  1. initialize with a constructor, supplying any needed parameters

    (a default constructor should be offered if at all possible)

  2. Attach EnvironmentObservers, to update GUIs or trace output

    (via attachEnvironmentListener)

    See EnvironmentObserver for a fuller description of the type of events the environment is expected to generate for the observer.

  3. Add additional agents and/or objects

    (via addEnvironmentObject, addAgent. Note that at least one Counter should always be added. And of course it's not very interesting if you don't add any agents.)

    Environment objects are JavaBeans, which allows the EnvironmentObservers to receive notifications of each change in their properties.

  4. run()

    which, in a general implementation, should repeat executeStep until isDone() returns true

    where executeStep consists of:

    and somewhere in there you should eventually set isDone to true!

    Version:
    $Rev$
    Author:
    aaron@cs
    See Also:
    "Russell & Norvig p38"

    Method Summary
     void addAgent(A theAgent)
              Adds an Agent to the environment.
     void addEnvironmentObject(EnvironmentObject theObject)
              Adds an EnvironmentObject to the environment.
     void addEnvironmentObserver(EnvironmentObserver<K,P,A> theObserver)
              Adds an EnvironmentObserver, which will be spun into a separate thread, and receive messages when events happen in the environment.
     void agentDrivenChange(A theAgent, K theAction)
              Changes the state of zero or more environment objects, given an agent and the action that the agent selected.
     void dynamicChange()
              Considers the current state of the environmentObjects, and changes zero or more objects.
     void executeStep()
              Performs one step of the simulated environment.
     java.util.Collection<A> getAgents()
              Returns a collection of all agent objects, which is a (possibly empty) subset of the collection of all objects.
     Counter getCounter()
              getCounter returns the environment's Counter object, which is included in the EnvironmentObjects collection.
     java.util.Collection<EnvironmentObject> getEnvironmentObjects()
              Returns a collection of all environment objects.
     void initialSetup()
              Performs any default initialization of the environment.
     boolean isDone()
              Returns true when the environment state is done changing.
     java.util.Set<P> perceptsForAgent(A theAgent)
              Returns a set (possibly empty) of percepts for the given agent.
     void run()
              Repeatedly calls executeStep until isDone is true.
     void startingToRunSetup()
              Performs initialization of agents, etc.
     

    Method Detail

    isDone

    boolean isDone()
    Returns true when the environment state is done changing.


    perceptsForAgent

    java.util.Set<P> perceptsForAgent(A theAgent)
    Returns a set (possibly empty) of percepts for the given agent. Presumably, this method examines the state of environment objects (including the agent itself) to select the appropriate percept.

    Note that in particular, percept might include the outcome of the agent's most recent action.


    addEnvironmentObject

    void addEnvironmentObject(EnvironmentObject theObject)
    Adds an EnvironmentObject to the environment. Once added, an object cannot be removed, though note that all EnvironmentObjects support an isAlive() property which might be set to false to indicate that an object is no longer active.

    Note that Agents, although they are also environment objects, should be added via the #addAgent() method.

    The first Counter added will be used as 'the' counter returned by #getCounter(); any subsequent counters will just be treated as another environment object.

    Parameters:
    theObject - the EnvironmentObject to add

    addEnvironmentObserver

    void addEnvironmentObserver(EnvironmentObserver<K,P,A> theObserver)
    Adds an EnvironmentObserver, which will be spun into a separate thread, and receive messages when events happen in the environment.

    Parameters:
    theObserver - the EnvironmentObserver to add.

    initialSetup

    void initialSetup()
    Performs any default initialization of the environment.

    This permits the environment itself to add a default set of objects, given parameters passed in the constructor. This step takes place *after* construction to permit EnvironmentObservers to be added before initialization.


    startingToRunSetup

    void startingToRunSetup()
    Performs initialization of agents, etc. as the environment begins to run.


    addAgent

    void addAgent(A theAgent)
    Adds an Agent to the environment. Note that Agents should be added here, rather than via #addEnvironmentObject.


    run

    void run()
    Repeatedly calls executeStep until isDone is true.


    executeStep

    void executeStep()
    Performs one step of the simulated environment. i.e. a. dynamicChange(), which changes zero or more objects spontaneously b. for agent in agents: p = perceptsForAgent(agent), which returns the set of percepts for the specified agent given the current state of the objects. action = agent.nextAction(p), which fetches the agent's chosen action agentDrivenChange(agent,action), which changes zero or more objects


    dynamicChange

    void dynamicChange()
    Considers the current state of the environmentObjects, and changes zero or more objects. May be deterministic or stochastic. All environments should update the state of their Counter object to increment the stepCounter.


    agentDrivenChange

    void agentDrivenChange(A theAgent,
                           K theAction)
    Changes the state of zero or more environment objects, given an agent and the action that the agent selected. This might involve changing the state of the agent, updating a map of locations, and updating a table of performance measures.

    Parameters:
    theAgent - the agent that just selected an action
    theAction - the action selected

    getEnvironmentObjects

    java.util.Collection<EnvironmentObject> getEnvironmentObjects()
    Returns a collection of all environment objects. This collection defines the state of the environment. Note that in particular implementations, the collection might be ordered.


    getAgents

    java.util.Collection<A> getAgents()
    Returns a collection of all agent objects, which is a (possibly empty) subset of the collection of all objects. For performance & convenience, an environment implementation might choose to maintain a separate collection of agents, but this method could also just filter the object collection for instances of Agent.


    getCounter

    Counter getCounter()

    getCounter returns the environment's Counter object, which is included in the EnvironmentObjects collection.

    This method is for convenient access to the counter. Note that particular Counter implementations might support more state than just the counter

    The Counter, unlike the agents, can simply be added via the #addEnvironmentObject method.