[WIP] Various Improvements

.gitignore

@@ -137,8 +137,9 @@ dmypy.json
 
 *.cproject
 
-# generated parser
+# generated parser and checksum
 src/scenic/syntax/parser.py
+src/scenic/syntax/.parser_checksum
 
 # generated media/output
 simulation.gif

docs/api.rst

@@ -30,8 +30,8 @@ the sampled values for all the global parameters and objects in the scene from t
 
 .. testcode::
 
-	import random, scenic
-	random.seed(12345)
+	import scenic
+	scenic.setSeed(12345)
 	scenario = scenic.scenarioFromString('ego = new Object with foo Range(0, 5)')
 	scene, numIterations = scenario.generate()
 	print(f'ego has foo = {scene.egoObject.foo}')
@@ -40,6 +40,13 @@ the sampled values for all the global parameters and objects in the scene from t
 
 	ego has foo = 2.083099362726706
 
+Utilities
+---------
+
+Scenic provides top level utility functions for functions like setting Scenic's random seed.
+
+.. autofunction:: scenic.setSeed
+
 Running Dynamic Simulations
 ---------------------------
 
@@ -173,6 +180,15 @@ it to the replay, but this greatly increases the size of the encoded simulation.
 	can return to one later for further analysis), but it is not guaranteed to be
 	compatible across major versions of Scenic.
 
+.. _xosc_export:
+
+OpenScenarioXML Export
+----------------------
+
+Scenic provides experimental support for exporting completed simulations via `toOpenScenario`.
+This function currently only supports cars and pedestrians, and may be subject to breaking changes
+in the future.
+
 .. seealso:: If you get exceptions or unexpected behavior when using the API, Scenic provides various debugging features: see :ref:`debugging`.
 
 .. rubric:: Footnotes

docs/options.rst

@@ -48,6 +48,8 @@ General Scenario Control
 	(although :mod:`random` and :mod:`numpy.random` should not be used in place of
 	Scenic's own sampling constructs in Scenic code).
 
+	The seed can be set programatically using `scenic.setSeed`.
+
 .. option:: --scenario <scenario>
 
 	If the given Scenic file defines multiple scenarios, select which one to run.

docs/reference/dynamic_scenarios.rst

@@ -33,12 +33,12 @@ In detail, a single time step of a dynamic simulation is executed according to t
 	   If the block executes a :keyword:`require` statement with a false condition, reject the simulation.
 	   If it executes :keyword:`terminate` or :keyword:`terminate simulation`, or finishes executing, go to step (e) below to stop the scenario.
 
-	e. If the scenario is stopping for one of the reasons above, first recursively stop any sub-scenarios it is running, then revert the effects of any :keyword:`override` statements it executed.
+	e. If the scenario is stopping for one of the reasons above, save the values of any :keyword:`record final` statements in the scenario, recursively stop any sub-scenarios it is running, then revert the effects of any :keyword:`override` statements it executed.
 	   Next, check if any of its :term:`temporal requirements` were not satisfied: if so, reject the simulation.
 	   Otherwise, the scenario returns to its parent scenario if it was invoked using :keyword:`do`; if it was the top-level scenario, or if it executed :keyword:`terminate simulation`, we set a flag indicating the top-level scenario has terminated.
 	   (We do not terminate immediately since we still need to check monitors in the next step.)
 
-2. Save the values of all :keyword:`record` statements, as well as :keyword:`record initial` statements if it is time step 0.
+2. Save the values of all :keyword:`record` statements in currently-running scenarios, as well as :keyword:`record initial` statements for scenarios which have just started.
 
 3. Run each :term:`monitor` instantiated in the currently-running scenarios for one time step (i.e. resume it until it executes :keyword:`wait`).
    If it executes a :keyword:`require` statement with a false condition, reject the simulation.
@@ -66,8 +66,7 @@ In detail, a single time step of a dynamic simulation is executed according to t
 
 9. Update every :term:`dynamic property` of every object to its current value in the simulator.
 
-10. If the simulation is stopping for one of the reasons above, first check if any of the :term:`temporal requirements` of any remaining scenarios were not satisfied: if so, reject the simulation.
-    Otherwise, save the values of any :keyword:`record final` statements.
+10. If the simulation is stopping for one of the reasons above, stop any remaining scenarios as in step (1e) above (including checking :term:`temporal requirements` and saving the values of :keyword:`record final` statements).
 
 
 .. rubric:: Footnotes

docs/reference/operators.rst

@@ -28,13 +28,27 @@ apparent heading of *OrientedPoint* [from *vector*]
 ---------------------------------------------------
 The apparent heading of the OrientedPoint, with respect to the line of sight from ego (or the position provided with the optional from vector)
 
+.. _apparent heading to {vector} [from {OrientedPoint}]:
+
+apparent heading to *vector* [from *OrientedPoint*]
+---------------------------------------------------
+The apparent heading to the vector, with respect to the line of sight from ego (or the OrientedPoint provided with the optional from OrientedPoint)
+
 .. _distance [from {vector}] to {vector}:
 .. _distance from:
 
 distance [from *vector*] to *vector*
 -------------------------------------
 The distance to the given position from ego (or the position provided with the optional from vector)
 
+.. _minimum distance [from {Object}] to {Object}:
+.. _minimum distance from:
+
+minimum distance [from *Object*] to *Object*
+--------------------------------------------
+The minimum distance to the given Object from ego (or the Object provided with the optional from Object). Unlike :ref:`distance from`, this operator takes into account the Objects' shapes, sizes, etc...
+
+
 .. _angle [from {vector}] to {vector}:
 
 angle [from *vector* ] to *vector*
@@ -75,6 +89,15 @@ Whether an `Object`/`Region` intersects another `Object`/`Region`, i.e. whether
 
 When working with 2D regions, it can be useful to check intersection with the :term:`footprint` of a region, e.g. when checking whether a car intersects a given lane. In this case, one would write :scenic:`car intersects lane.footprint` instead of :scenic:`car intersects lane`. For more details, see :term:`footprint`.
 
+.. _{vector} (ahead of | behind | left of | right of) {region}:
+
+*vector* (ahead of | behind | left of | right of) *OrientedPoint*
+-----------------------------------------------------------------
+Whether a vector is to a respective side of an `OrientedPoint` (i.e. within +- ~90 degrees from that direction), accounting for the heading of the `OrientedPoint`. These operators are convenient shorthand for comparing :sampref:`apparent heading to {vector} [from {OrientedPoint}]` to a range of values.
+
+Note: For vectors very close to a boundary point (i.e. an apparent heading to the vector in (89.99, 90.01) or (-89.99, -90.01) for "ahead of" and "behind"), both operators will resolve to False.
+
+Example: If an `OrientedPoint` had an apparent heading to a vector of 45 degrees, it would be both "ahead of" and "left of" the `OrientedPoint` but not "behind" or "right of".
 
 Orientation Operators
 =====================

docs/reference/statements.rst

@@ -285,7 +285,7 @@ The default mutation system adds Gaussian noise to the :prop:`position` and :pro
 record [initial | final] *value* [as *name*]
 ----------------------------------------------
 Record the value of an expression during each simulation.
-The value can be recorded at the start of the simulation (``initial``), at the end of the simulation (``final``), or at every time step (if neither ``initial`` nor ``final`` is specified).
+The value can be recorded at the start of the scenario (``initial``), at the end of the scenario (``final``), or at every time step during the scenario (if neither ``initial`` nor ``final`` is specified).
 The recorded values are available in the ``records`` dictionary of `SimulationResult`: its keys are the given names of the records (or synthesized names if not provided), and the corresponding values are either the value of the recorded expression or a tuple giving its value at each time step as appropriate.
 For debugging, the records can also be printed out using the :option:`--show-records` command-line option.
 

docs/simulators.rst

@@ -14,6 +14,10 @@ See the individual entries for details on each interface's capabilities and how
 	While Scenic aims to support multiple Python versions, some simulators may have more limited compatibility.
 	Be sure to check the documentation of each simulator to confirm which Python versions are supported.
 
+.. note::
+	Scenic also supports outputing data in formats that may be imported into other simulators and tools (e.g. :ref:`xosc_export`).
+	For more details, see :ref:`serialization`.
+
 .. contents:: List of Simulators
    :local:
 
@@ -163,7 +167,6 @@ This interface is part of the VerifAI toolkit; documentation and examples can be
 
 .. _VerifAI repository: https://github.com/BerkeleyLearnVerify/VerifAI
 
-
 Deprecated
 ==========
 

pyproject.toml

@@ -36,6 +36,7 @@ dependencies = [
 	"networkx >= 2.6",
 	"numpy >= 1.24",
 	"opencv-python ~= 4.5",
+	"optuna ~= 4.0",
 	"pegen >= 0.3.0",
 	"pillow >= 9.1",
 	'pygame-ce >= 2.5.7, <3; python_version >= "3.10"',
@@ -60,6 +61,9 @@ metadrive = [
 	"metadrive-simulator >= 0.4.3",
 	"sumolib >= 1.21.0",
 ]
+openscenario = [
+	"scenariogeneration"
+]
 test = [	# minimum dependencies for running tests (used for tox virtualenvs)
 	"pytest >= 7.0.0",
 	"pytest-cov >= 3.0.0",
@@ -68,6 +72,7 @@ test = [	# minimum dependencies for running tests (used for tox virtualenvs)
 test-full = [  # like 'test' but adds dependencies for optional features
 	"scenic[test]",       # all dependencies from 'test' extra above
 	"scenic[guideways]",  # for running guideways modules
+	"scenic[openscenario]",
 	"astor >= 0.8.1",
 	'carla >= 0.9.12; python_version <= "3.12" and (platform_system == "Linux" or platform_system == "Windows")',
 	"dill",

src/scenic/__init__.py

@@ -2,6 +2,7 @@
 
 import scenic.core.errors as _errors
 from scenic.core.errors import setDebuggingOptions
+from scenic.core.utils import setSeed
 from scenic.syntax.translator import scenarioFromFile, scenarioFromString
 
 _errors.showInternalBacktrace = False  # see comment in errors module

src/scenic/__main__.py

@@ -185,8 +185,7 @@
     if args.verbosity >= 1:
         print(f"Using random seed = {args.seed}")
 
-    random.seed(args.seed)
-    numpy.random.seed(args.seed)
+    scenic.setSeed(args.seed)
 
 # Load scenario from file
 if args.verbosity >= 1:

src/scenic/core/distributions.py

@@ -126,6 +126,7 @@ def __init__(self, dependencies):
                 props.update(requiredProperties(dep))
         super().__init__(props, deps)
         self._conditioned = self  # version (partially) conditioned on requirements
+        self._conditionTarget = False
 
     @staticmethod
     def sampleAll(quantities):
@@ -172,6 +173,8 @@ def deserializeValue(self, serializer, values):
 
     def conditionTo(self, value):
         """Condition this value to another value with the same conditional distribution."""
+        assert not self._conditionTarget, "Attempted to double condition!"
+        value._conditionTarget = True
         assert isinstance(value, Samplable)
         self._conditioned = value
 
@@ -182,6 +185,17 @@ def evaluateIn(self, context):
         assert all(not needsLazyEvaluation(dep) for dep in value._dependencies)
         return value
 
+    def recursiveDependencies(self):
+        self = self._conditioned
+        deps = set(
+            itertools.chain.from_iterable(
+                dep.recursiveDependencies() for dep in self._dependencies
+            )
+        )
+        if isinstance(self, Distribution) and not self._deterministic:
+            deps.add(self)
+        return deps
+
 
 class ConstantSamplable(Samplable):
     """A samplable which always evaluates to a constant value.
@@ -1076,6 +1090,7 @@ def cdf(mean, stddev, x):
         return (1 + math.erf((x - mean) / (sqrt2 * stddev))) / 2
 
     @staticmethod
+    @distributionFunction
     def cdfinv(mean, stddev, x):
         import scipy  # slow import not often needed
 
@@ -1271,7 +1286,7 @@ def supportInterval(self):
 
     def __repr__(self):
         weights = self.weights
-        if all(weight == weights[0] for weight in weights):
+        if not weights or all(weight == weights[0] for weight in weights):
             return f"DiscreteRange({self.low!r}, {self.high!r})"
         else:
             return f"DiscreteRange({self.low!r}, {self.high!r}, {self.weights})"

src/scenic/core/dynamics/behaviors.py

@@ -109,7 +109,7 @@ def alarmHandler(signum, frame):
             try:
                 actions = self._runningIterator.send(None)
             except StopIteration:
-                actions = ()  # behavior ended early
+                return None
         return actions
 
     def _stop(self, reason=None):
@@ -124,18 +124,39 @@ def _isFinished(self):
     def _invokeInner(self, agent, subs):
         import scenic.syntax.veneer as veneer
 
-        assert len(subs) == 1
-        sub = subs[0]
-        if not isinstance(sub, Behavior):
-            raise TypeError(f"expected a behavior, got {sub}")
-        sub._start(agent)
-        with veneer.executeInBehavior(sub):
+        # Validate all inner behaviors
+        for sub in subs:
+            if not isinstance(sub, Behavior):
+                raise TypeError(f"expected a behavior, got {sub}")
+            sub._start(agent)
+
+        # Create a generator for each inner behavior that yields the appropriate actions, cleaning up when done.
+        def make_inner_generator(sub):
             try:
-                yield from sub._runningIterator
+                while sub._isRunning:
+                    actions = sub._step()
+                    if actions is None:
+                        return
+                    yield actions
             finally:
                 if sub._isRunning:
                     sub._stop()
 
+        inner_generators = [make_inner_generator(sub) for sub in subs]
+
+        # Yield from a generator that zips all the inner generators together without padding, until all inner generators have terminated.
+        while True:
+            try:
+                raw_actions_list = next(itertools.zip_longest(*inner_generators))
+                yield tuple(
+                    filter(
+                        lambda x: x is not None,
+                        itertools.chain.from_iterable(raw_actions_list),
+                    )
+                )
+            except StopIteration:
+                return
+
     def __repr__(self):
         items = itertools.chain(
             (repr(arg) for arg in self._args),