soar.client

Soar client entrypoint.

Classes and functions for interacting with Soar in general. This module serves as the main entrypoint to the package. Projects desiring to invoke a Soar instance should import this module and call soar.client.main().

Examples

This will invoke a GUI instance, which will terminate when the main window is closed, and always return 0:

from soar.client import main
return_value = main()

If invoking a headless instance, paths to brain and world files should be specified:

from soar.client import main
return_value = main(brain_path='path/to/brain.py', world_path='path/to/world.py', headless=True)

In this case, the return value will be 1 if an exception occurred and 0 otherwise.

Logging is handled via passing a path:

from soar.client import main
return_value = main(logfile='path/to/logfile')

or, using a file-like object:

from soar.client import main
return_value = main(logfile=open('path/to/logfile', 'r+'))
soar.client.future(name, *args, **kwargs)

Adds a function with data for the client to execute in the future, by putting it on the client’s internal queue.

Note that if an exception or controller failure occurs, the future may never be executed as the client’s queue will be purged.

Certain futures accept an optional callback parameter.

Parameters:
  • name – The future to execute, defined in soar.common. and contained in future_map.
  • *args – The variable length arguments to pass to the function.
  • **kwargs – The keyword arguments to pass to the function.
soar.client.future_map = {0: <function make_gui at 0x7fadba93d7b8>, 1: <function load_brain at 0x7fadba93d840>, 2: <function load_world at 0x7fadba93d8c8>, 3: <function make_controller at 0x7fadba93da60>, 4: <function start_controller at 0x7fadba93dbf8>, 5: <function pause_controller at 0x7fadba93dc80>, 6: <function step_controller at 0x7fadba93dd08>, 7: <function stop_controller at 0x7fadba93de18>, 8: <function shutdown_controller at 0x7fadba93dea0>, 9: <function controller_complete at 0x7fadba9381e0>, 11: <function controller_io_error at 0x7fadba9380d0>, 12: <function controller_failure at 0x7fadba938158>, 13: <function logging_error at 0x7fadba93df28>, 14: <function step_finished at 0x7fadba93dd90>, 15: <function gui_load_brain at 0x7fadba93d950>, 16: <function gui_load_world at 0x7fadba93d9d8>, 17: <function set_hooks at 0x7fadba93d730>, 18: <function nop at 0x7fadba93d6a8>, 19: <function draw at 0x7fadba93db70>, 20: <function make_world_canvas at 0x7fadba93dae8>, 21: <function gui_error at 0x7fadba938048>}

A mapping from future names to their actual functions.

soar.client.main(brain_path=None, world_path=None, headless=False, logfile=None, step_duration=0.1, realtime=True, options=None)

Main entrypoint, for use from the command line or other packages. Starts a Soar instance.

Parameters:
  • brain_path (optional) – The path to the initial brain to load. Required if headless, otherwise not required.
  • world_path (optional) – The path to the initial world to load. Required if headless, otherwise not required.
  • headless (bool) – If True, run Soar in headless mode, immediately running a simulation.
  • logfile (optional) – The path to the log file, or a file-like object to log data to.
  • step_duration (float) – The duration of a controller step, in seconds. By default, 0.1 seconds.
  • realtime (bool) – If True, the controller will never sleep to make a step last the proper length. Instead, it will run as fast as possible.
  • options (dict) – The keyword arguments to pass to the robot whenever it is loaded.
Returns:

0 if Soar’s execution successfully completed, 1 otherwise.