DOCSEARCHbyAlgolia
Submit Docs

ScienceWorld Documentation

repository·main·Indexed 18 days ago

https://github.com/allenai/scienceworld

A text-based virtual environment for training and evaluating agents on elementary science curriculum tasks. It features a Scala-based simulator with a Python API, supporting various science tasks (e.g., boiling, melting, conductivity testing), environment simplifications, and a web-based user console. The documentation covers installation, task loading, and internal simulation language components such as the Interpreter, ActionRequestDef, and ActionTrigger.

Tokens
10.1K
Snippets
22
Records
47
Agent score
63%

What's inside ScienceWorld

  1. Apply environment simplifications

    main

    Simplifications can be applied to make the environment easier for agents to learn. These can be passed via the --simplifications-preset CLI argument or the simplifications argument in the Python API.

    Individual Simplifications

    • teleportAction: Allows agents to instantly move to any location.
    • openDoors: All doors are open by default.
    • selfWateringFlowerPots: Automatically waters all flower pots.
    • noElectricalAction: Disables electrical actions.
    • openContainers: All containers are open by default.

    The easy Preset

    Setting --simplifications-preset easy applies the following:

    • teleportAction
    • openDoors
    • selfWateringFlowerPots
    • noElectricalAction (for non-connectivity tasks)
    WARNING

    The easy preset does not include openContainers. You must add it manually if desired.

  2. Install ScienceWorld

    main

    ScienceWorld requires Java 1.8+ and Python 3.8+.

    1. Setup Environment

    It is recommended to use a conda environment:

    conda create --name scienceworld python=3.8
conda activate scienceworld

    2. Install Package

    You can install via PyPI:

    pip install scienceworld

    Or install from source in development mode:

    git clone https://github.com/allenai/ScienceWorld.git
cd ScienceWorld
pip install .
    conda create --name scienceworld python=3.8
conda activate scienceworld
pip install scienceworld

  3. Build ScienceWorld from source (Developers)

    main

    ScienceWorld is written in Scala (2.12.9) and uses sbt to compile into a JAR. The Python API interfaces with this JAR using py4j.

    1. Install Prerequisites

    Install Java 1.8+ and sbt (Scala Build Tool).

    On Ubuntu:

    sudo apt-get install openjdk-21-jdk

echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee /etc/apt/sources.list_old.list
curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo tee /etc/apt/trusted.gpg.d/sbt.asc
sudo apt-get update
sudo apt-get install sbt

    2. Compile the JAR

    Run the following command to compile the Scala code into a JAR:

    ./simulator/package.sh

    3. Reinstall Python Package

    If you have modified the Scala code, re-run the package script and then reinstall the Python package in editable mode:

    ./simulator/package.sh
pip install -e .

  4. Run the ScienceWorld Web Server Demo

    main

    You can run a web-based user console that allows interaction through a web browser.

    1. Install with webserver extras

    conda create --name scienceworld python=3.8
conda activate scienceworld
pip install scienceworld[webserver]

    2. Start the server

    python examples/scienceworld-web-server-example.py

    Once running, access the interface at http://localhost:8080.

    pip install scienceworld[webserver]
python examples/scienceworld-web-server-example.py

  5. Use the Interpreter to run simulation language commands

    main

    The Interpreter class is the core execution engine for the ScienceWorld simulation language. It manages object instantiation, variable scoping, expression evaluation, and conditional logic.

    Key capabilities include:

    • Object Management: Instantiates objects using class definitions, handles constructors, and manages an objectTreeRoot.
    • Variable Scoping: Uses a ScopedVariableLUT to manage variable visibility and lifecycles.
    • Expression Evaluation: Supports numbers, strings, booleans, identifiers, object properties, operators (math), and built-in functions.
    • Control Flow: Implements conditional logic (if statements) and loop ranges (for loops).
    • Console Output: Captures simulation output via a consoleOutputBuffer.
    // Example of initializing an Interpreter (conceptual based on constructor)
val interpreter = new Interpreter(
  definesLUT = Map("MY_DEFINE" -> "value"),
  classLUT = myClassDefinitions,
  actionRunner = myActionRunner
)

  6. Use Container objects to hold items

    main

    In ScienceWorld, Container objects are a type of EnvObject that can hold other items. Containers are categorized by their properties, such as whether they can be closed or what material they are made of.

    Common container types include:

    • Cup: A base class for various handheld containers.
    • MetalPot, GlassCup, PlasticCup, WoodCup, TinCup, PaperCup, CeramicCup: Specific implementations of cups/pots.
    • WoodBowl, Jug, GlassJar: Other specialized containers.
    • FlowerPot and SelfWateringFlowerPot: Containers that can interact with Water objects.
    • BookShelf: A container specifically designed to hold Book objects.

    Containers use getReferents() to provide a set of names that can be used to identify them in the environment, often including descriptions of their current contents (e.g., "cup containing water").

  7. Identify containers by their content-based referents

    main

    Containers in ScienceWorld generate dynamic referents based on what they contain. The method mkContentReferences is used to extend a set of base names (like "cup") with descriptive names that include the contents (e.g., "cup containing water and sand"). This allows agents or users to refer to an object by its state.

    When calling getReferents() on a container, the returned set includes:

    1. The base names (e.g., "pot", "metal pot").
    2. The object's specific name.
    3. A descriptive name including its contents.

  8. How conditional logic and loops work in the Interpreter

    main

    The Interpreter handles control flow through specific evaluation methods:

    Conditional Logic

    conditionalLogic(conditionExpr, trueBranch) evaluates a ConditionExpr. If the condition evaluates to true, the interpreter pushes a new scope onto the scopedVariableLUT and executes the trueBranch statements. The scope is popped once the branch execution is complete.

    For Loops

    evaluateForRange(range) parses ForRange objects (e.g., for (x <- start until end by step)). It validates that start, until, and by (if provided) are all valid integers before returning a ForRangeParsed object used to drive the loop execution.

  9. Understand Document types and hierarchy

    main

    The scienceworld.objects.document package defines a hierarchy of readable objects used within the simulator. All these objects extend EnvObject and share properties like being made of PaperProp and being MoveableProperties.

    Core Types:

    • Document: The base class for all readable items. Contains title and contents.
    • Paper: A specific type of document. If it has no content, it is treated as blank.
    • ColoredPaper: A document that specifically lacks text but has a color name.
    • Recipe: A document designed to hold instructions for mixing items.
    • Book: A more complex document containing author and title. Includes several hardcoded implementations for specific literary works (e.g., BookMobyDick, BookFrankenstein).

  10. Simulation Language Statement Types and Behaviors

    main

    The ScienceWorld simulation language interpreter supports several categories of statements that control the simulation state, variables, and objects. When writing simulation scripts, you can use the following statement types:

    Variable and Assignment

    • Assignment: Sets a variable to an expression value. If firstdefinition is true, the variable must not already exist; otherwise, it must already be defined.
    • AssignmentObjProp: Sets a property on an object. Note that if the property is defined by a class's property function, it may be overwritten in the next simulation tick.
    • AssignmentArrayElem: Sets a specific element in an array using an index expression.

    Object Manipulation

    • AddObjToWorld: Adds a new object to the simulation's object tree.
    • DeleteObject: Removes an object from its container, effectively deleting it from the world.
    • MoveObject: Moves an object from one container (e.g., a room or another object) to a new container.

    Control Flow

    • Return: Exits the current execution block and returns a DynamicValue.
    • Exit: Performs a hard exit of the system with a specified exitCode.
    • ForLoop: Iterates over a range defined by a start, end, and step.
    • ForLoopArrayElem: Iterates over the elements of an array. If the target is an object, it iterates over the object's contained objects.
    • IfStatement: Supports IF, ELSEIF, and ELSE conditional modes.

    Array Operations

    • ArrayAppend: Appends a value to an existing array.
    • ArrayRemove: Removes a specific value from an array.

    Actions and I/O

    • RequestAction: Posts an action request (e.g., an agent performing a task) using a predicate name and a list of object parameters.
    • Print / PrintLog: Outputs a string to the standard output or the simulation log.

  11. Use ActionExpr types to define action patterns

    main

    Action patterns are composed of ActionExpr implementations. These expressions define how objects, text, or logical choices are matched during an action request:

    • ActionExprOR(orElements: List[String]): Represents a choice between multiple string elements (e.g., "red OR blue").
    • ActionExprIdentifier(identifier: String): Represents a reference to an object by its identifier. When resolved via mkHumanReadableInstance, it produces a descriptive string including the object's name and its container hierarchy (e.g., "in the orange tree, in flower pot 3").
    • ActionExprObject(obj: EnvObject, referent: String): Holds a specific EnvObject and its string referent used for matching.
    • ActionExprText(text: String): Represents a literal text match.

  12. Run ScienceWorld examples

    main

    After installation, you can run pre-built examples to interact with the environment.

    Run a random agent

    To run a random agent on a specific task (e.g., task 13) for a set number of episodes with an 'easy' simplification preset:

    python examples/random_agent.py --task-num=13 --num-episodes=5 --simplifications-preset easy

    Run a human console

    To interact with the environment manually via a user console (e.g., task 3):

    python examples/human.py --task-num=3 --num-episodes=5
    python examples/random_agent.py --task-num=13 --num-episodes=5 --simplifications-preset easy

python examples/human.py --task-num=3 --num-episodes=5