From 3ab7ac0e72e39084c26c25951eb30a76c89eed9a Mon Sep 17 00:00:00 2001 From: James Arruda Date: Tue, 10 Dec 2024 13:20:25 -0500 Subject: [PATCH] Updating documents for library name change. --- docs/source/conf.py | 26 +++++----- docs/source/index.md | 6 +-- .../user_guide/how_tos/active_states.rst | 10 ++-- .../user_guide/how_tos/communications.rst | 8 +-- .../user_guide/how_tos/decision_tasks.rst | 14 ++--- .../user_guide/how_tos/entity_naming.rst | 8 +-- docs/source/user_guide/how_tos/events.rst | 22 ++++---- docs/source/user_guide/how_tos/geography.rst | 52 +++++++++---------- .../user_guide/how_tos/motion_manager.rst | 30 +++++------ docs/source/user_guide/how_tos/nucleus.rst | 4 +- .../user_guide/how_tos/random_numbers.rst | 4 +- .../user_guide/how_tos/resource_states.rst | 2 +- .../user_guide/how_tos/stage_variables.rst | 14 ++--- .../user_guide/how_tos/state_sharing.rst | 4 +- .../user_guide/how_tos/task_networks.rst | 30 +++++------ docs/source/user_guide/how_tos/typing.rst | 14 ++--- .../user_guide/tutorials/best_practices.rst | 2 +- .../user_guide/tutorials/first_simulation.rst | 34 ++++++------ .../user_guide/tutorials/interrupts.rst | 16 +++--- .../source/user_guide/tutorials/rehearsal.rst | 2 +- 20 files changed, 151 insertions(+), 151 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0f2c09e..0fdfda5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -42,19 +42,19 @@ myst_heading_anchors = 2 myst_substitutions = { "rtd": "[Read the Docs](https://readthedocs.org/)", - "Actor": "{py:class}`Actor `", - "State": "{py:class}`~upstage.states.State`", - "Task": "{py:class}`~upstage.task.Task`", - "TaskNetwork": "{py:class}`~upstage.task_network.TaskNetwork`", - "EnvironmentContext": "{py:class}`~upstage.base.EnvironmentContext`", - "UpstageBase": "{py:class}`~upstage.base.UpstageBase`", - "NamedEntity": "{py:class}`~upstage.base.NamedUpstageEntity`", - "LinearChangingState": "{py:class}`~upstage.states.LinearChangingState`", - "CartesianLocation": "{py:class}`~upstage.data_types.CartesianLocation`", - "GeodeticLocationChangingState": "{py:class}`~upstage.states.GeodeticLocationChangingState`", - "ResourceState": "{py:class}`~upstage.states.ResourceState`", - "SelfMonitoringStore": "{py:class}`~upstage.stores.SelfMonitoringStore`", - "DecisionTask": "{py:class}`~upstage.task.DecisionTask`", + "Actor": "{py:class}`Actor `", + "State": "{py:class}`~upstage_des.states.State`", + "Task": "{py:class}`~upstage_des.task.Task`", + "TaskNetwork": "{py:class}`~upstage_des.task_network.TaskNetwork`", + "EnvironmentContext": "{py:class}`~upstage_des.base.EnvironmentContext`", + "UpstageBase": "{py:class}`~upstage_des.base.UpstageBase`", + "NamedEntity": "{py:class}`~upstage_des.base.NamedUpstageEntity`", + "LinearChangingState": "{py:class}`~upstage_des.states.LinearChangingState`", + "CartesianLocation": "{py:class}`~upstage_des.data_types.CartesianLocation`", + "GeodeticLocationChangingState": "{py:class}`~upstage_des.states.GeodeticLocationChangingState`", + "ResourceState": "{py:class}`~upstage_des.states.ResourceState`", + "SelfMonitoringStore": "{py:class}`~upstage_des.stores.SelfMonitoringStore`", + "DecisionTask": "{py:class}`~upstage_des.task.DecisionTask`", } diff --git a/docs/source/index.md b/docs/source/index.md index a5ccc03..702a6bc 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -52,7 +52,7 @@ Alternatively, you can download UPSTAGE and install it manually. Clone, or downl Note that the tests include the two full examples from the documentation. ```console -(venv) $ pip install uptage[test] +(venv) $ pip install upstage-des[test] (venv) $ pytest ``` @@ -61,8 +61,8 @@ Note that the tests include the two full examples from the documentation. Unless you're adding to the codebase, you won't need to run the `sphinx-apidoc` command. ```console -(venv) $ pip install upstage[docs] -(venv) $ sphinx-apidoc -o .\docs\source\ .\src\upstage\ .\src\upstage\test\ +(venv) $ pip install upstage-des[docs] +(venv) $ sphinx-apidoc -o .\docs\source\ .\src\upstage_des\ .\src\upstage_des\test\ (venv) $ sphinx-build -b html .\docs\source\ .\docs\build\ ``` diff --git a/docs/source/user_guide/how_tos/active_states.rst b/docs/source/user_guide/how_tos/active_states.rst index fd53fe9..2e551c8 100644 --- a/docs/source/user_guide/how_tos/active_states.rst +++ b/docs/source/user_guide/how_tos/active_states.rst @@ -7,7 +7,7 @@ Active States are an UPSTAGE feature where states are told how to update themsel For example, a fuel depot may dispense fuel at a given rate for some amount of time. An employee may monitor that level at certain times. UPSTAGE allows the state to hold its own update logic, rather than the employee code needing to know when the fuel started changing, at what rate, etc. -Active states are stopped and started with :py:meth:`~upstage.actor.Actor.activate_state` and :py:meth:`~upstage.actor.Actor.deactivate_state`. +Active states are stopped and started with :py:meth:`~upstage_des.actor.Actor.activate_state` and :py:meth:`~upstage_des.actor.Actor.deactivate_state`. Active states are automatically stopped when a Task is interrupted. @@ -78,7 +78,7 @@ They accept a speed and list of waypoints in their activation. .. code-block:: python - from upstage.utils import waypoint_time_and_dist + from upstage_des.utils import waypoint_time_and_dist class FlatlandCar(UP.Actor): location: UP.CartesianLocation = UP.CartesianLocationChangingState() @@ -147,7 +147,7 @@ The ``GeodeticLocationChangingState`` works the same way. Creating your own ================= -To create you own Active State, subclass :py:class:`~upstage.states.ActiveState`. +To create you own Active State, subclass :py:class:`~upstage_des.states.ActiveState`. The bare minimum is to implement the ``_active`` method. @@ -156,8 +156,8 @@ Here is an example of an ActiveState that changes according to an exponent. .. code-block:: python :linenos: - from upstage.states import ActiveState - from upstage.actor import Actor + from upstage_des.states import ActiveState + from upstage_des.actor import Actor class ExponentChangingState(ActiveState): """A state that changes according to: x_t = x_0 + at^(b)""" diff --git a/docs/source/user_guide/how_tos/communications.rst b/docs/source/user_guide/how_tos/communications.rst index accfc8d..f9febbd 100644 --- a/docs/source/user_guide/how_tos/communications.rst +++ b/docs/source/user_guide/how_tos/communications.rst @@ -2,11 +2,11 @@ Communications ============== -UPSTAGE provides a built-in method for passing communications between actors. The :py:class:`~upstage.communications.comms.CommsManager` class +UPSTAGE provides a built-in method for passing communications between actors. The :py:class:`~upstage_des.communications.comms.CommsManager` class allows actors to send messages while allowing for simplified retry attempts and timeouts. It also allows for communications blocking to be turned on and off on a point to point basis. -The :py:class:`~upstage.communications.comms.Message` class is used to describe a message, although strings and dictionaries can +The :py:class:`~upstage_des.communications.comms.Message` class is used to describe a message, although strings and dictionaries can also be passed as messages, and UPSTAGE will convert them into the ``Message`` class. The communications manager needs to be instantiated and run, and any number of them can be run, to represent different modes of @@ -15,7 +15,7 @@ comms managers. .. code-block:: python - import upstage.api as UP + import upstage_des.api as UP class Worker(UP.Actor): walkie = UP.CommunicationStore(mode="UHF") @@ -36,7 +36,7 @@ comms managers. loudspeaker_comms.run() The ``CommsManager`` class allows for explicitly connecting actors and the store that will receive messages, but using the -:py:class:`~upstage.states.CommunicationStore` lets the manager auto-discover the proper store for a communications mode, letting +:py:class:`~upstage_des.states.CommunicationStore` lets the manager auto-discover the proper store for a communications mode, letting the simulation designer only need to pass the source actor, destination actor, and message information to the manager. To send a message, use the comm manager's ``make_put`` method to return an UPSTAGE event to yield on to send the message. diff --git a/docs/source/user_guide/how_tos/decision_tasks.rst b/docs/source/user_guide/how_tos/decision_tasks.rst index cfac113..a3e4fb7 100644 --- a/docs/source/user_guide/how_tos/decision_tasks.rst +++ b/docs/source/user_guide/how_tos/decision_tasks.rst @@ -2,19 +2,19 @@ Decision Tasks ============== -Decision tasks are :py:class:`~upstage.task.Task`s that take zero time and were briefly demonstrated in :doc:`Rehearsal `. The purpose of a -Decision task is to allow decision making and :py:class:`~upstage.task_networks.TaskNetwork` routing without moving the simulation clock and do so inside of a Task Network. +Decision tasks are :py:class:`~upstage_des.task.Task`s that take zero time and were briefly demonstrated in :doc:`Rehearsal `. The purpose of a +Decision task is to allow decision making and :py:class:`~upstage_des.task_networks.TaskNetwork` routing without moving the simulation clock and do so inside of a Task Network. A decision task must implement two methods: -* :py:class:`~upstage.task.DecisionTask.make_decision` -* :py:class:`~upstage.task.DecisionTask.rehearse_decision` +* :py:class:`~upstage_des.task.DecisionTask.make_decision` +* :py:class:`~upstage_des.task.DecisionTask.rehearse_decision` Neither method outputs anything. The expectation is that inside these methods you modify the task network using: -* :py:meth:`upstage.actor.Actor.clear_task_queue`: Empty a task queue -* :py:meth:`upstage.actor.Actor.set_task_queue`: Add tasks to an empty queue (by string name) - you must empty the queue first. -* :py:meth:`upstage.actor.Actor.set_knowledge`: Modify knowledge +* :py:meth:`upstage_des.actor.Actor.clear_task_queue`: Empty a task queue +* :py:meth:`upstage_des.actor.Actor.set_task_queue`: Add tasks to an empty queue (by string name) - you must empty the queue first. +* :py:meth:`upstage_des.actor.Actor.set_knowledge`: Modify knowledge The difference between making and rehearsing the decision is covered in the tutorial. The former method is called during normal operations of UPSTAGE, and the latter is called during a rehearsal of the task or network. It is up the user to ensure that no side-effects occur during the rehearsal that would touch non-rehearsing state, actors, or other data. diff --git a/docs/source/user_guide/how_tos/entity_naming.rst b/docs/source/user_guide/how_tos/entity_naming.rst index 7958ac5..4cac60a 100644 --- a/docs/source/user_guide/how_tos/entity_naming.rst +++ b/docs/source/user_guide/how_tos/entity_naming.rst @@ -2,12 +2,12 @@ Named Entities ============== -Named entities are an :py:class:`~upstage.base.EnvironmentContext` and :py:class:`~upstage.base.NamedUpstageEntity` enabled feature where you can store instances in particular "entity groups" to gather -them from later. UPSTAGE's :py:class:`~upstage.actor.Actor` inherits from :py:class:`~upstage.base.NamedUpstageEntity`, giving all Actors the feature. +Named entities are an :py:class:`~upstage_des.base.EnvironmentContext` and :py:class:`~upstage_des.base.NamedUpstageEntity` enabled feature where you can store instances in particular "entity groups" to gather +them from later. UPSTAGE's :py:class:`~upstage_des.actor.Actor` inherits from :py:class:`~upstage_des.base.NamedUpstageEntity`, giving all Actors the feature. -All Actors are retrievable with the :py:meth:`~upstage.base.UpstageBase.get_actors` method if they inherit from Actor. +All Actors are retrievable with the :py:meth:`~upstage_des.base.UpstageBase.get_actors` method if they inherit from Actor. -Entities are retrievable with :py:meth:`~upstage.base.UpstageBase.get_all_entity_groups` and :py:meth:`~upstage.base.UpstageBase.get_entity_group`. +Entities are retrievable with :py:meth:`~upstage_des.base.UpstageBase.get_all_entity_groups` and :py:meth:`~upstage_des.base.UpstageBase.get_entity_group`. Defining a named entity is done in the class definition: diff --git a/docs/source/user_guide/how_tos/events.rst b/docs/source/user_guide/how_tos/events.rst index 520c453..16293e9 100644 --- a/docs/source/user_guide/how_tos/events.rst +++ b/docs/source/user_guide/how_tos/events.rst @@ -8,12 +8,12 @@ All events accept a ``rehearsal_time_to_complete`` argument. The available UPSTAGE events are: -:py:class:`~upstage.events.Event` +:py:class:`~upstage_des.events.Event` --------------------------------- Mimics SimPy's raw ``Event``, useful for marking pauses until a success. -See :py:meth:`~upstage.actor.Actor.create_knowledge_event` for a use case. +See :py:meth:`~upstage_des.actor.Actor.create_knowledge_event` for a use case. One use case is the knowledge event, which enables a way to publish and event to an actor, and have some other source ``succeed`` it. @@ -31,7 +31,7 @@ One use case is the knowledge event, which enables a way to publish and event to subordinate.succeed_knowledge_event(name="pause", some_data={...}) -:py:class:`~upstage.events.Wait` +:py:class:`~upstage_des.events.Wait` -------------------------------- A standard SimPy timeout. Can be explicit or generate from a random uniform distribution. @@ -44,7 +44,7 @@ The random uniform distribution accepts an input for the rehearsal time, while t yield UP.Wait.from_random_uniform(low, high, rehearsal_time_to_complete=high) -:py:class:`~upstage.events.Get` +:py:class:`~upstage_des.events.Get` ------------------------------- Get from a store or container. @@ -60,7 +60,7 @@ Get from a store or container. assert get_event.get_value() == amount -:py:class:`~upstage.events.FilterGet` +:py:class:`~upstage_des.events.FilterGet` ------------------------------------- A get with a filter function, used for SimPy's ``FilterStore``. @@ -70,9 +70,9 @@ A get with a filter function, used for SimPy's ``FilterStore``. item = yield get_event -:py:class:`~upstage.resources.sorted.SortedFilterGet` +:py:class:`~upstage_des.resources.sorted.SortedFilterGet` ----------------------------------------------------- -A get with a filter or sorting function, used with :py:class:`~upstage.resources.sorted.SortedFilterStore`, and others. +A get with a filter or sorting function, used with :py:class:`~upstage_des.resources.sorted.SortedFilterStore`, and others. .. code-block:: python @@ -84,7 +84,7 @@ A get with a filter or sorting function, used with :py:class:`~upstage.resources item = yield get_event -:py:class:`~upstage.events.Put` +:py:class:`~upstage_des.events.Put` ------------------------------- Put something into a store or container @@ -99,7 +99,7 @@ Put something into a store or container yield UP.Put(some_store, amount) -:py:class:`~upstage.events.ResourceHold` +:py:class:`~upstage_des.events.ResourceHold` ---------------------------------------- Put and release holds on limited resources. @@ -114,7 +114,7 @@ Put and release holds on limited resources. # Now you've given it back -:py:class:`~upstage.events.All` +:py:class:`~upstage_des.events.All` ------------------------------- Succeed when all passed events succeed. @@ -128,7 +128,7 @@ Succeed when all passed events succeed. assert wait_event.is_complete() -:py:class:`~upstage.events.Any` +:py:class:`~upstage_des.events.Any` ------------------------------- Succeed when any passed events succeed diff --git a/docs/source/user_guide/how_tos/geography.rst b/docs/source/user_guide/how_tos/geography.rst index e23300d..99796c4 100644 --- a/docs/source/user_guide/how_tos/geography.rst +++ b/docs/source/user_guide/how_tos/geography.rst @@ -2,7 +2,7 @@ Geography ========= -UPSTAGE has built-in features for simple geographic math and behaviors. These features are built up into a :py:class:`~upstage.states.GeodeticLocation` state. +UPSTAGE has built-in features for simple geographic math and behaviors. These features are built up into a :py:class:`~upstage_des.states.GeodeticLocation` state. Discrete Event Simulation does not lend itself well to geography and repeated distance checking (for something like a sensor, e.g.), so UPSTAGE provides the capability to schedule intersections of moving actors and stationary sensors. Those features are covered in the :doc:`Motion Manager ` documentation. @@ -19,7 +19,7 @@ Geographic Data Types and State These are the built-in features that use geography: -:py:class:`~upstage.data_types.GeodeticLocation` +:py:class:`~upstage_des.data_types.GeodeticLocation` ------------------------------------------------ This data type stores a Latitude / Longitude / Altitude (optional) for a point around the globe. @@ -34,7 +34,7 @@ Two geodetic locations can be subtracted from each other to get their great circ .. code-block:: python - from upstage.geography import Spherical + from upstage_des.geography import Spherical with UP.EnvironmentContext(): UP.add_stage_variable("stage_model", Spherical) @@ -51,7 +51,7 @@ Two geodetic locations can be subtracted from each other to get their great circ straight_line = loc1.straight_line_distance(loc2) >>> 1049.3621152419862 -Location instances *must* be created within an :py:class:`~upstage.base.EnvironmentContext` context, otherwise they won't have access to the geographic model at runtime. Additionally, these stage variables must be set: +Location instances *must* be created within an :py:class:`~upstage_des.base.EnvironmentContext` context, otherwise they won't have access to the geographic model at runtime. Additionally, these stage variables must be set: * ``stage_model`` must be set to be either ``Spherical`` or ``WGS84``, or whatever class performs ``.distance`` on lat/lon/altitude pairs. * ``distance_units``: One of: "m", "km", "mi", "nmi", or "ft" @@ -65,14 +65,14 @@ The distance between two points is the great circle distance, and altitude is ig that any speeds you specify are implicitly ground speed, which is more useful. However, if a sensor is looking straight up, the distance to an object 30 thousand feet up shouldn't be zero. To account for altitude in the distance, use -:py:func:`~upstage.data_types.GeodeticLocation.dist_with_altitude` or :py:func:`~upstage.data_types.GeodeticLocation.straight_line_distance`. +:py:func:`~upstage_des.data_types.GeodeticLocation.dist_with_altitude` or :py:func:`~upstage_des.data_types.GeodeticLocation.straight_line_distance`. Note that the intersection models (covered elsewhere) do distance checks in ECEF, not with the ``GeodeticLocation`` subtraction method, so you don't have to worry about this distinction for those motion features. Once a ``GeodeticLocation`` is created, it cannot be changed. This is for safety of not changing a location from underneath code that expects to use it a certain way. Some methods are provided to help get copies: -* :py:meth:`~upstage.data_types.GeodeticLocation.copy`: Make a copy of the location -* :py:meth:`~upstage.data_types.GeodeticLocation.to_radians`: Make a copy of the location with the latitude and longitude in radians -* :py:meth:`~upstage.data_types.GeodeticLocation.to_degrees`: Make a copy of the location with the latitude and longitude in degrees +* :py:meth:`~upstage_des.data_types.GeodeticLocation.copy`: Make a copy of the location +* :py:meth:`~upstage_des.data_types.GeodeticLocation.to_radians`: Make a copy of the location with the latitude and longitude in radians +* :py:meth:`~upstage_des.data_types.GeodeticLocation.to_degrees`: Make a copy of the location with the latitude and longitude in degrees For comparison, here's what ``pyproj`` gets for the calculations (pyproj is not currently a dependency for UPSTAGE): @@ -80,7 +80,7 @@ For comparison, here's what ``pyproj`` gets for the calculations (pyproj is not .. code-block:: python import pyproj - from upstage.api import unit_convert + from upstage_des.api import unit_convert # NOTE: Numpy is not a requirement of UPSTAGE import numpy as np @@ -107,7 +107,7 @@ Both distances are within .07% of UPSTAGE's calculations. -:py:class:`~upstage.states.GeodeticLocationChangingState` +:py:class:`~upstage_des.states.GeodeticLocationChangingState` --------------------------------------------------------- This is a State that allows activation and movement along great-circle waypoints with altitude changing along the waypoints. When initializing, it accepts a ``GeodeticLocation`` object, and it returns those when you ask it for @@ -115,7 +115,7 @@ the state's value. Here is its basic usage: .. code-block:: python - from upstage.utils import waypoint_time_and_dist + from upstage_des.utils import waypoint_time_and_dist class Plane(UP.Actor): location: UP.GeodeticLocation = UP.GeodeticLocationChangingState(recording=True) @@ -147,7 +147,7 @@ the state's value. Here is its basic usage: ) ... -The :py:func:`~upstage.utils.waypoint_time_and_dist` function is a convenience function that gets the great circle distance and time over a set of waypoints to help schedule the arrival time. +The :py:func:`~upstage_des.utils.waypoint_time_and_dist` function is a convenience function that gets the great circle distance and time over a set of waypoints to help schedule the arrival time. Cartesian Locations @@ -155,7 +155,7 @@ Cartesian Locations These aren't geographic, but they serve the same purpose, so we include them here. -:py:class:`~upstage.data_types.CartesianLocation` +:py:class:`~upstage_des.data_types.CartesianLocation` ------------------------------------------------- This data type stores an X / Y / Z (optional) location in 2 or 3D space (z is set to zero if not included). @@ -189,7 +189,7 @@ We still allow you to set distance and altitude units because the 'z' value coul The distance is always implied to be in ``distance_units``, without setting it. If the z component is in a different unit, then we need to know both to get the straight-line distance. -:py:class:`~upstage.states.CartesianLocationChangingState` +:py:class:`~upstage_des.states.CartesianLocationChangingState` ---------------------------------------------------------- This active state works the exact same as the ``GeodeticLocationChangingState`` , except that it requires waypoints to be ``CartesianLocation`` s. @@ -198,9 +198,9 @@ This active state works the exact same as the ``GeodeticLocationChangingState`` Geography Sub-Module ==================== -The :py:mod:`upstage.geography` module contains: +The :py:mod:`upstage_des.geography` module contains: -:py:class:`~upstage.geography.spherical.Spherical` +:py:class:`~upstage_des.geography.spherical.Spherical` -------------------------------------------------- This class contains methods for finding distances, positions, and for segmenting great-circle paths on the assumption of a spherical earth. @@ -209,11 +209,11 @@ Typically, you will not need to use these methods directly, but they are avaiabl The most useful methods, besides distance, may be: -#. :py:meth:`~upstage.geography.spherical.Spherical.geo_linspace`, which will give you evenly spaced points along a great circle route. -#. :py:meth:`~upstage.geography.spherical.Spherical.geo_circle`, which will give you evently spaced points to draw a circle in spherical coordinates -#. :py:meth:`~upstage.geography.spherical.Spherical.point_from_bearing_dist`, which gives you a point relative to a base location at some distance and bearing. +#. :py:meth:`~upstage_des.geography.spherical.Spherical.geo_linspace`, which will give you evenly spaced points along a great circle route. +#. :py:meth:`~upstage_des.geography.spherical.Spherical.geo_circle`, which will give you evently spaced points to draw a circle in spherical coordinates +#. :py:meth:`~upstage_des.geography.spherical.Spherical.point_from_bearing_dist`, which gives you a point relative to a base location at some distance and bearing. -:py:class:`~upstage.geography.wgs84.WGS84` +:py:class:`~upstage_des.geography.wgs84.WGS84` ------------------------------------------- This class contains methods for finding distances, positions, and for segmenting great-circle paths on the assumption of a WGS84 ellipsoid. These methods take longer to run than the Spherical version, @@ -223,14 +223,14 @@ Typically, you will not need to use these methods directly, but they are avaiabl The most useful methods, besides distance, may be: -#. :py:meth:`~upstage.geography.spherical.WGS84.geo_linspace`, which will give you evenly spaced points along a great circle route. -#. :py:meth:`~upstage.geography.spherical.WGS84.geo_circle`, which will give you evently spaced points to draw a circle in spherical coordinates -#. :py:meth:`~upstage.geography.spherical.WGS84.point_from_bearing_dist`, which gives you a point relative to a base location at some distance and bearing. +#. :py:meth:`~upstage_des.geography.spherical.WGS84.geo_linspace`, which will give you evenly spaced points along a great circle route. +#. :py:meth:`~upstage_des.geography.spherical.WGS84.geo_circle`, which will give you evently spaced points to draw a circle in spherical coordinates +#. :py:meth:`~upstage_des.geography.spherical.WGS84.point_from_bearing_dist`, which gives you a point relative to a base location at some distance and bearing. -:py:mod:`upstage.geography.intersections` +:py:mod:`upstage_des.geography.intersections` ------------------------------------------- -The :py:func:`~upstage.geography.intersections.get_intersection_locations` function calculates an intersection between a great circle path and a sphere. It can be passed an instance of ``Spherical`` or ``WGS84`` +The :py:func:`~upstage_des.geography.intersections.get_intersection_locations` function calculates an intersection between a great circle path and a sphere. It can be passed an instance of ``Spherical`` or ``WGS84`` to do distance calculations with. The intersections are calculated by taking evenly spaced points along the great circle path and finding the two points where an intersection occurs between. It then divides that segment more finely, and calculates @@ -245,7 +245,7 @@ Storing Geographic Data While the storage and instantiation of geographic objects is mostly within your control, the main caveat is that a ``GeodeticLocation`` requires the stage to exist. This means that you can only create a ``GeodeticLocation`` within an ``EnvironmentContext``. -To store data in an easily passable format, UPSTAGE has a :py:class:`~upstage.data_types.GeodeticLocationData` class. +To store data in an easily passable format, UPSTAGE has a :py:class:`~upstage_des.data_types.GeodeticLocationData` class. This class instantiates with the same inputs as the ``GeodeticLocation``, and has a single method: ``make_location()``. That method generates the ``GeodeticLocation``, letting you pass around the data object until you're ready for it inside an environment context. diff --git a/docs/source/user_guide/how_tos/motion_manager.rst b/docs/source/user_guide/how_tos/motion_manager.rst index ea1fa79..14dd1e9 100644 --- a/docs/source/user_guide/how_tos/motion_manager.rst +++ b/docs/source/user_guide/how_tos/motion_manager.rst @@ -8,7 +8,7 @@ There are two motion managers. One uses intersection calculations to maintain a motion detection for when the "sensor" and the viewed entities are both moving. The built-in ``<>LocationChangingState`` states work with any of the motion managers in the background, by alerting them when those states are made activate. If you want to control which Actors are visible to the -motion manager, there is the :py:class:`~upstage.states.DetectabilityState` that can be given to an actor and set to ``False``. +motion manager, there is the :py:class:`~upstage_des.states.DetectabilityState` that can be given to an actor and set to ``False``. Define the Motion Manager @@ -17,8 +17,8 @@ Define the Motion Manager .. code-block:: python :linenos: - from upstage.motion.geodetic_model import subdivide_intersection - from upstage.geography.intersections import get_intersection_locations + from upstage_des.motion.geodetic_model import subdivide_intersection + from upstage_des.geography.intersections import get_intersection_locations with UP.EnvironmentContext(): motion = UP.SensorMotionManager( @@ -29,8 +29,8 @@ Define the Motion Manager UP.add_stage_variable("intersection_model", get_intersection_locations) * Line 1-2: Import one of the intersection models and a support function (more on this below) -* Line 5: Create the :py:class:`~upstage.motion.SensorMotionManager` and give it the intersection model - * The other option is the :py:class:`~upstage.stepped_motion.SteppedMotionManager` class. (Does not need an intersection) +* Line 5: Create the :py:class:`~upstage_des.motion.SensorMotionManager` and give it the intersection model + * The other option is the :py:class:`~upstage_des.stepped_motion.SteppedMotionManager` class. (Does not need an intersection) * Line 9: Add the motion manager to the stage so that the ``<>LocationChangingState`` s can find it. * Line 10: Add the intersection helper function to the stage so the SensorMotionManager class can find it. @@ -40,20 +40,20 @@ in the background. Intersection Models ------------------- -There are two intersection models for ``Geodetic`` locations, and one model for ``Cartesian``. The Stepped motion manager does not require one, it uses :py:func:`~upstage.data_types.GeodeticLocation.straight_line_distance` at a given rate. +There are two intersection models for ``Geodetic`` locations, and one model for ``Cartesian``. The Stepped motion manager does not require one, it uses :py:func:`~upstage_des.data_types.GeodeticLocation.straight_line_distance` at a given rate. -* :py:func:`~upstage.motion.geodetic_model.subdivide_intersection`: The approximate intersection method with subdivided search, good for WGS84 coordinates. +* :py:func:`~upstage_des.motion.geodetic_model.subdivide_intersection`: The approximate intersection method with subdivided search, good for WGS84 coordinates. * This requires the stage variable ``intersection_model`` to be set. - * The only available intersection model is :py:func:`~upstage.geography.intersections.get_intersection_locations` + * The only available intersection model is :py:func:`~upstage_des.geography.intersections.get_intersection_locations` -* :py:func:`~upstage.motion.geodetic_model.analytical_intersection`: An exact intersection using a Spherical earth model. Incompatible with the WGS84 stage model. -* :py:func:`~upstage.motion.cartesian_model.cartesian_linear_intersection`: An exact intersection using for XYZ cartesian space. +* :py:func:`~upstage_des.motion.geodetic_model.analytical_intersection`: An exact intersection using a Spherical earth model. Incompatible with the WGS84 stage model. +* :py:func:`~upstage_des.motion.cartesian_model.cartesian_linear_intersection`: An exact intersection using for XYZ cartesian space. -The :py:func:`~upstage.geography.intersections.get_intersection_locations` function, required by the subdividing intersection, is what actually finds the intersections. The ``subdivide_intersection`` is +The :py:func:`~upstage_des.geography.intersections.get_intersection_locations` function, required by the subdividing intersection, is what actually finds the intersections. The ``subdivide_intersection`` is a passthrough function that handles the different earth models, stage variables, and conversion to the format UPSTAGE requires in the ``SensorMotionManager``. The intersection model itself does not have -to know about UPSTAGE. If you created a ``partial`` of a version of the ``subdivide_intersection`` that took the intersection model as an argument, you would get the same result without needing the stage variable. +to know about upstage_des. If you created a ``partial`` of a version of the ``subdivide_intersection`` that took the intersection model as an argument, you would get the same result without needing the stage variable. Sensor Requirements and Example @@ -68,8 +68,8 @@ All UPSTAGE does is call one of those methods according to the schedule. .. code-block:: python - from upstage.utils import waypoint_time_and_dist - from upstage.motion.cartesian_model import cartesian_linear_intersection + from upstage_des.utils import waypoint_time_and_dist + from upstage_des.motion.cartesian_model import cartesian_linear_intersection class Bird(UP.Actor): location = UP.CartesianLocationChangingState() @@ -204,5 +204,5 @@ Notice the slight inaccuracy in the position due to the time stepping. .. note:: The stepped manager is more flexible to the kinds of things that can be detected. You can use - :py:meth:`~upstage.motion.stepped_motion.SteppedMotionManager.add_detectable` to add anything with a + :py:meth:`~upstage_des.motion.stepped_motion.SteppedMotionManager.add_detectable` to add anything with a position. diff --git a/docs/source/user_guide/how_tos/nucleus.rst b/docs/source/user_guide/how_tos/nucleus.rst index 3ff4f3f..ba00402 100644 --- a/docs/source/user_guide/how_tos/nucleus.rst +++ b/docs/source/user_guide/how_tos/nucleus.rst @@ -22,7 +22,7 @@ The basic syntax is this: nuc.add_network(task_net, ["state name to watch", "other state"]) When any state given to the nucleus changes, nucleus pushes an interrupt to the task network. That interrupt is passed down -as a cause to ``on_interrupt`` as an instance of type :py:class:`~upstage.nucleus.NucleusInterrupt`. +as a cause to ``on_interrupt`` as an instance of type :py:class:`~upstage_des.nucleus.NucleusInterrupt`. .. code-block:: python @@ -134,7 +134,7 @@ A use case for Nucleus is when multiple task networks are sharing a single state a task cannot interrept itself. If a TaskNetwork changes a state that it is watching, SimPy will fail. It -What follows is an example that implements a nucleus allocation. This is not recommended, but is included to demonstrate how far you can stretch Nucleus and UPSTAGE. Ultimately, +What follows is an example that implements a nucleus allocation. This is not recommended, but is included to demonstrate how far you can stretch Nucleus and upstage_des. Ultimately, it is just running on SimPy and you can do what you like. Here are some issues/caveats with the following example: * None of the tasks are rehearsal-safe (this is OK if you're not going to rehearse) diff --git a/docs/source/user_guide/how_tos/random_numbers.rst b/docs/source/user_guide/how_tos/random_numbers.rst index 61a20ad..e09483a 100644 --- a/docs/source/user_guide/how_tos/random_numbers.rst +++ b/docs/source/user_guide/how_tos/random_numbers.rst @@ -4,14 +4,14 @@ Random Numbers Random numbers are not supplied by UPSTAGE, you are responsible for rolling dice on your own. -However, UPSTAGE does use them in one area, which is in :py:class:`~upstage.events.Wait`, in the :py:meth:`~upstage.events.Wait.from_random_uniform` method. +However, UPSTAGE does use them in one area, which is in :py:class:`~upstage_des.events.Wait`, in the :py:meth:`~upstage_des.events.Wait.from_random_uniform` method. The built-in python ``random`` module is used by default, and you can find it on ``stage.random``. It can be instantiated in a few ways: .. code-block:: python from random import Random - from upstage.api import UpstageBase, EnvironmentContext + from upstage_des.api import UpstageBase, EnvironmentContext base = UpstageBase() diff --git a/docs/source/user_guide/how_tos/resource_states.rst b/docs/source/user_guide/how_tos/resource_states.rst index a0722f3..bc5667b 100644 --- a/docs/source/user_guide/how_tos/resource_states.rst +++ b/docs/source/user_guide/how_tos/resource_states.rst @@ -23,7 +23,7 @@ The obvious question is, why? The following works just fine: .. code-block:: python - import upstage.api as UP + import upstage_des.api as UP import simpy as SIM class CheckoutLane(UP.Actor): diff --git a/docs/source/user_guide/how_tos/stage_variables.rst b/docs/source/user_guide/how_tos/stage_variables.rst index cc86e91..056a321 100644 --- a/docs/source/user_guide/how_tos/stage_variables.rst +++ b/docs/source/user_guide/how_tos/stage_variables.rst @@ -4,7 +4,7 @@ Stage Variables The ``stage`` is an UPSTAGE feature to allow thread-safe "global" variables accessible by any Actor or Task. -To add variables to the stage, within the :py:class:`~upstage.base.EnvironmentContext` manager use the :py:func:`~upstage.base.add_stage_variable` function. +To add variables to the stage, within the :py:class:`~upstage_des.base.EnvironmentContext` manager use the :py:func:`~upstage_des.base.add_stage_variable` function. Once you set a stage variable, it cannot be changed. This is intentional, as the stage is meant to be static. Anything that changes should go through SimPy or UPSTAGE tasks, states, or processes. @@ -39,14 +39,14 @@ SimPy or UPSTAGE tasks, states, or processes. Expected Stage Variables =========================== -Some variables are expected to exist on the stage for some features. These are found in the :py:class:`~upstage.base.StageProtocol` protocol, +Some variables are expected to exist on the stage for some features. These are found in the :py:class:`~upstage_des.base.StageProtocol` protocol, and are listed below: -* "altitude_units": A string of "ft", "m", or other distance unit. See :py:func:`~upstage.units.convert.unit_convert` for a list. +* "altitude_units": A string of "ft", "m", or other distance unit. See :py:func:`~upstage_des.units.convert.unit_convert` for a list. * "distance_units": A string of distance units * "stage_model": A model to use for Geodetic calculations. See :doc:`geography` for more. * "intersection_model": A model to use for motion manager. See :doc:`geography` and :doc:`motion_manager` for more. -* "time_unit": Units of time. See :py:func:`~upstage.units.convert.unit_convert` for a list. +* "time_unit": Units of time. See :py:func:`~upstage_des.units.convert.unit_convert` for a list. If they are not set and you use a feature that needs them, you'll get a warning about not being able to find a stage variable. @@ -54,7 +54,7 @@ If they are not set and you use a feature that needs them, you'll get a warning Accessing Stage through UpstageBase =================================== -The :py:class:`~upstage.base.UpstageBase` class can be inherited to provide access to ``self.env`` and ``self.stage`` in any object, not just +The :py:class:`~upstage_des.base.UpstageBase` class can be inherited to provide access to ``self.env`` and ``self.stage`` in any object, not just actors and tasks. The following snippets shows how you might use it for pure SimPy capabilities. .. code-block:: python @@ -68,14 +68,14 @@ actors and tasks. The following snippets shows how you might use it for pure Sim self.env.process(_proc()) -Accessing Stage through upstage.api +Accessing Stage through upstage_des.api =================================== For convenience, you can also do the following: .. code-block:: python - import upstage.api as UP + import upstage_des.api as UP with UP.EnvironmentContext() as env: UP.add_stage_variable("altitude_units", "centimeters") diff --git a/docs/source/user_guide/how_tos/state_sharing.rst b/docs/source/user_guide/how_tos/state_sharing.rst index 6bd8b63..b8a111b 100644 --- a/docs/source/user_guide/how_tos/state_sharing.rst +++ b/docs/source/user_guide/how_tos/state_sharing.rst @@ -4,7 +4,7 @@ State Sharing State sharing is a way to share a state on an actor between multiple task networks. -The only currently implemented feature that shares state is the :py:class:`~upstage.state_sharing.SharedLinearChangingState`. +The only currently implemented feature that shares state is the :py:class:`~upstage_des.state_sharing.SharedLinearChangingState`. This is an advanced feature that will require a user to subclass and create their own sharing state for their specific use case. @@ -12,7 +12,7 @@ This is an advanced feature that will require a user to subclass and create thei Shared Linear Changing State ---------------------------- -The :py:class:`~upstage.state_sharing.SharedLinearChangingState` allows multiple networks to draw from a linear changing state. See the ``test_nucleus_state_share`` test for a complete example. +The :py:class:`~upstage_des.state_sharing.SharedLinearChangingState` allows multiple networks to draw from a linear changing state. See the ``test_nucleus_state_share`` test for a complete example. In that example, a mothership refuels a flyer, both of which draw from the same ``SharedLinearChangingState`` fuel level. In that example, the flyer actor doesn't directly draw from the mothership. Instead, the flyer tells the mothership that a draw will happen, and the mothership creates a new task network that draws that fuel from itself. That fuel is in addition to fuel burned while flying. diff --git a/docs/source/user_guide/how_tos/task_networks.rst b/docs/source/user_guide/how_tos/task_networks.rst index ef4ea92..fcee40f 100644 --- a/docs/source/user_guide/how_tos/task_networks.rst +++ b/docs/source/user_guide/how_tos/task_networks.rst @@ -68,8 +68,8 @@ Task Networks work by running a defined queue of task names, then by selecting ` You can modify the task network flow using: -* :py:meth:`upstage.actor.Actor.clear_task_queue`: Empty a task queue -* :py:meth:`upstage.actor.Actor.set_task_queue`: Add tasks to an empty queue (by string name) - you must empty the queue first. +* :py:meth:`upstage_des.actor.Actor.clear_task_queue`: Empty a task queue +* :py:meth:`upstage_des.actor.Actor.set_task_queue`: Add tasks to an empty queue (by string name) - you must empty the queue first. These two methods are preferred since they prevent the risks of appending to a queue without looking at the queue. @@ -78,30 +78,30 @@ Introspecting the Task Network The task network queues can be viewed using: -* :py:meth:`upstage.actor.Actor.get_task_queue`: This requires the network name. -* :py:meth:`upstage.actor.Actor.get_all_task_queues`: This will return for all the networks on the actor. +* :py:meth:`upstage_des.actor.Actor.get_task_queue`: This requires the network name. +* :py:meth:`upstage_des.actor.Actor.get_all_task_queues`: This will return for all the networks on the actor. You can get the names and processes of tasks that are running (and their network names) using: -* :py:meth:`upstage.actor.Actor.get_running_task`: Returns a dataclass with the task name and process object of the task on the defined network. -* :py:meth:`upstage.actor.Actor.get_running_tasks`: Returns the same as above, but keyed on task network names. +* :py:meth:`upstage_des.actor.Actor.get_running_task`: Returns a dataclass with the task name and process object of the task on the defined network. +* :py:meth:`upstage_des.actor.Actor.get_running_tasks`: Returns the same as above, but keyed on task network names. -You would want the processes to interrupt them, but you can also use :py:meth:`upstage.actor.Actor.interrupt_network` to do that. +You would want the processes to interrupt them, but you can also use :py:meth:`upstage_des.actor.Actor.interrupt_network` to do that. Note that the task queue methods won't return the current tasks, just what's defined to run next. Use the running task methods to find the current task. A note on TaskNetworkFactory ---------------------------- -The :py:class:`~upstage.task_network.TaskNetworkFactory` class has some convience methods for creating factories from typical use cases: +The :py:class:`~upstage_des.task_network.TaskNetworkFactory` class has some convience methods for creating factories from typical use cases: -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_single_looping`: From a single task, make a network that loops on it. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_single_looping`: From a single task, make a network that loops on it. * Useful for a Singleton task that, for example, receives communications and farms them out or manages other task networks. -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_single_terminating`: A network that does one task, then freezes for the rest of the simulation. -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_ordered_looping`: A series of tasks with no branching that loops. -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_single_looping`: A series of tasks with no branching that terminates at the end. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_single_terminating`: A network that does one task, then freezes for the rest of the simulation. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_ordered_looping`: A series of tasks with no branching that loops. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_single_looping`: A series of tasks with no branching that terminates at the end. -A terminating task network contains a :py:class:`~upstage.task.TerminalTask` task at the end, which waits on an un-succeedable event in a rehearsal-safe manner. +A terminating task network contains a :py:class:`~upstage_des.task.TerminalTask` task at the end, which waits on an un-succeedable event in a rehearsal-safe manner. Running Multiple Networks @@ -110,8 +110,8 @@ Running Multiple Networks An actor has no limits to the number of Task Networks it can run. As long as the Actor's states do not overlap in the networks, they can all run in "parallel". Simply keep the network names unique. -When adding parallel task networks, you can avoid a name clash with :py:meth:`upstage.actor.Actor.suggest_network_name`, and use the resulting name to add the network. When you are done with a network, -it can be deleted from the actor's attributes using: :py:meth:`upstage.actor.Actor.delete_task_network`. The task network will still be allowed to run, so make sure it's in a terminal state first. It will +When adding parallel task networks, you can avoid a name clash with :py:meth:`upstage_des.actor.Actor.suggest_network_name`, and use the resulting name to add the network. When you are done with a network, +it can be deleted from the actor's attributes using: :py:meth:`upstage_des.actor.Actor.delete_task_network`. The task network will still be allowed to run, so make sure it's in a terminal state first. It will de-clutter the task network introspection methods, though. See :doc:`Nucleus ` and :doc:`State Sharing ` for features related to inter-Task Networks "communication". diff --git a/docs/source/user_guide/how_tos/typing.rst b/docs/source/user_guide/how_tos/typing.rst index 466e5ae..1c64f14 100644 --- a/docs/source/user_guide/how_tos/typing.rst +++ b/docs/source/user_guide/how_tos/typing.rst @@ -31,11 +31,11 @@ Later, your IDE will know that any ``Gardener`` instance's ``skill_level`` attri These states already have an assigned type, or have a limited scope of types: -1. :py:class:`~upstage.states.DetectabilityState`: This state is a boolean -2. :py:class:`~upstage.states.CartesianLocationChangingState`: The output is of type ``CartesianLocation`` -3. :py:class:`~upstage.states.GeodeticLocationChangingState`: The output is of type ``GeodeticLocation`` -4. :py:class:`~upstage.states.ResourceState`: The type must be a ``simpy.Store`` or ``simpy.Container`` (or a subclass). You can still define the type. -5. :py:class:`~upstage.states.CommunicationStore`: This is of type ``simpy.Store`` +1. :py:class:`~upstage_des.states.DetectabilityState`: This state is a boolean +2. :py:class:`~upstage_des.states.CartesianLocationChangingState`: The output is of type ``CartesianLocation`` +3. :py:class:`~upstage_des.states.GeodeticLocationChangingState`: The output is of type ``GeodeticLocation`` +4. :py:class:`~upstage_des.states.ResourceState`: The type must be a ``simpy.Store`` or ``simpy.Container`` (or a subclass). You can still define the type. +5. :py:class:`~upstage_des.states.CommunicationStore`: This is of type ``simpy.Store`` ---------------------- Task and Process Types @@ -46,8 +46,8 @@ Tasks and simpy processes have output types that are ``Generator`` types. UPSTAG .. code-block:: python from simpy import Environment - from upstage.type_help import TASK_GEN, SIMPY_GEN - from upstage.api import Task, Actor, process, InterruptStates + from upstage_des.type_help import TASK_GEN, SIMPY_GEN + from upstage_des.api import Task, Actor, process, InterruptStates class SomeTask(Task): def task(self, *, actor: Actor) -> TASK_GEN: diff --git a/docs/source/user_guide/tutorials/best_practices.rst b/docs/source/user_guide/tutorials/best_practices.rst index 477b4e8..8211621 100644 --- a/docs/source/user_guide/tutorials/best_practices.rst +++ b/docs/source/user_guide/tutorials/best_practices.rst @@ -85,7 +85,7 @@ When testing for ``PLANNING_FACTOR_OBJECT``, do so in a method on the task that return 3.0 return item["process_time"] - def task(self, *, actor: UP.Actor) -> upstage.type_help.TASK_GEN: + def task(self, *, actor: UP.Actor) -> upstage_des.type_help.TASK_GEN: item = yield UP.Get(actor.some_store, planning_time_to_complete=1.23) time = self._get_time(item) yield UP.Wait(time) diff --git a/docs/source/user_guide/tutorials/first_simulation.rst b/docs/source/user_guide/tutorials/first_simulation.rst index 2d032ef..3ddf3e5 100644 --- a/docs/source/user_guide/tutorials/first_simulation.rst +++ b/docs/source/user_guide/tutorials/first_simulation.rst @@ -22,7 +22,7 @@ We prefer this syntax for importing UPSTAGE and SimPy: .. code-block:: python - import upstage.api as UP + import upstage_des.api as UP import simpy as SIM print("hello world") @@ -58,7 +58,7 @@ The ``scan_speed`` state is defined to require a ``float`` type (UPSTAGE will th state is similar, except that a default value of 120 minutes is supplied. .. note:: - There is no explicit time dimension in UPSTAGE. The clock units are up to the user, and the user must ensure that all times are properly defined. If you set a stage variable of ``time_unit``, + There is no explicit time dimension in upstage_des. The clock units are up to the user, and the user must ensure that all times are properly defined. If you set a stage variable of ``time_unit``, it will correct the time for debug logging strings (into hours) only. @@ -170,7 +170,7 @@ Let's define the tasks that wait for a customer and check the customer out. :linenos: from typing import Generator - from upstage.type_help import TASK_GEN + from upstage_des.type_help import TASK_GEN class WaitInLane(UP.Task): @@ -309,23 +309,23 @@ All ``Task`` s should yield UPSTAGE events, with one exception. A SimPy ``Proces The event types are: -#. :py:class:`~upstage.events.Event`: Mimics SimPy's raw ``Event``, useful for marking pauses until a success. +#. :py:class:`~upstage_des.events.Event`: Mimics SimPy's raw ``Event``, useful for marking pauses until a success. - * See :py:meth:`~upstage.actor.Actor.create_knowledge_event` for a use case. + * See :py:meth:`~upstage_des.actor.Actor.create_knowledge_event` for a use case. -#. :py:class:`~upstage.events.All`: Succeed when all passed events succeed +#. :py:class:`~upstage_des.events.All`: Succeed when all passed events succeed -#. :py:class:`~upstage.events.Any`: Succeed when any passed events succeed +#. :py:class:`~upstage_des.events.Any`: Succeed when any passed events succeed -#. :py:class:`~upstage.events.Get`: Get from a store or container +#. :py:class:`~upstage_des.events.Get`: Get from a store or container -#. :py:class:`~upstage.events.FilterGet`: A get with a filter function +#. :py:class:`~upstage_des.events.FilterGet`: A get with a filter function -#. :py:class:`~upstage.events.Put`: Put something into a store or container +#. :py:class:`~upstage_des.events.Put`: Put something into a store or container -#. :py:class:`~upstage.events.ResourceHold`: Put and release holds on limited resources +#. :py:class:`~upstage_des.events.ResourceHold`: Put and release holds on limited resources -#. :py:class:`~upstage.events.Wait`: A standard SimPy timeout +#. :py:class:`~upstage_des.events.Wait`: A standard SimPy timeout ------------------------------------ @@ -391,17 +391,17 @@ You can either start a loop on a single task, or define an initial queue through A note on TaskNetworkFactory ---------------------------- -The :py:class:`~upstage.task_network.TaskNetworkFactory` class has some convience methods for creating factories from typical use cases: +The :py:class:`~upstage_des.task_network.TaskNetworkFactory` class has some convience methods for creating factories from typical use cases: -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_single_looping`: From a single task, make a network that loops itself. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_single_looping`: From a single task, make a network that loops itself. * Useful for a Singleton task that, for example, receives communications and farms them out or manages other task networks. -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_single_terminating`: A network that does one task, then freezes for the rest of the simulation. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_single_terminating`: A network that does one task, then freezes for the rest of the simulation. -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_ordered_looping`: A series of tasks with no branching that loops. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_ordered_looping`: A series of tasks with no branching that loops. -#. :py:meth:`~upstage.task_network.TaskNetworkFactory.from_single_looping`: A series of tasks with no branching that terminates at the end. +#. :py:meth:`~upstage_des.task_network.TaskNetworkFactory.from_single_looping`: A series of tasks with no branching that terminates at the end. -------------------- diff --git a/docs/source/user_guide/tutorials/interrupts.rst b/docs/source/user_guide/tutorials/interrupts.rst index 3a3de08..1a39ad2 100644 --- a/docs/source/user_guide/tutorials/interrupts.rst +++ b/docs/source/user_guide/tutorials/interrupts.rst @@ -126,15 +126,15 @@ UPSTAGE's interrupt handling system mitigates these key sources of error or frus To access these features, do the following: -#. Implement ``on_interrupt`` in the :py:class:`~upstage.task.Task` class. +#. Implement ``on_interrupt`` in the :py:class:`~upstage_des.task.Task` class. #. Optionally: use the ``marker`` features in the task and interrupt methods. - * :py:meth:`~upstage.task.Task.set_marker` + * :py:meth:`~upstage_des.task.Task.set_marker` - * :py:meth:`~upstage.task.Task.get_marker` + * :py:meth:`~upstage_des.task.Task.get_marker` - * :py:meth:`~upstage.task.Task.clear_marker` + * :py:meth:`~upstage_des.task.Task.clear_marker` We'll start simple, then add complexity to the interrupt. @@ -143,7 +143,7 @@ Here's what the above process would look like as an UPSTAGE Task: .. code-block:: python :linenos: - import upstage.api as UP + import upstage_des.api as UP import simpy as SIM from typing import Any @@ -199,7 +199,7 @@ Then, when you run it: Now the task is small and informative about what it's supposed to do when its not interrupted. The marker features let us set and get introspection data cleanly. -Notice also that the ``Get()`` call does not need to be cancelled by the user; UPSTAGE does that for us (for all :py:class:`~upstage.events.BaseEvent` subclasses that implement ``cancel``). +Notice also that the ``Get()`` call does not need to be cancelled by the user; UPSTAGE does that for us (for all :py:class:`~upstage_des.events.BaseEvent` subclasses that implement ``cancel``). Some additional details: @@ -216,7 +216,7 @@ Some additional details: INTERRUPT Types and Setting Markers ----------------------------------- -Interrupts allow 4 different outcomes to the task, which are signalled by the :py:class:`~upstage.task.InterruptStates` Enum (or :py:class:`~upstage.task.Task.INTERRUPT` as part of ``self``). The first +Interrupts allow 4 different outcomes to the task, which are signalled by the :py:class:`~upstage_des.task.InterruptStates` Enum (or :py:class:`~upstage_des.task.Task.INTERRUPT` as part of ``self``). The first three can be returned from ``on_interrupt`` to define how to handle the interrupt. #. ``END``: Ends the task right there (and moves on in the task network). This cancels the pending event(s). @@ -316,7 +316,7 @@ The interrupt automatically deactivates all states, keeping your Actors safe fro Getting the Process =================== -If an actor is running a task network, you will need to get the current Task process to send an interrupt. Do that with the :py:meth:`upstage.actor.Actor.get_running_tasks` method. +If an actor is running a task network, you will need to get the current Task process to send an interrupt. Do that with the :py:meth:`upstage_des.actor.Actor.get_running_tasks` method. .. code-block:: python diff --git a/docs/source/user_guide/tutorials/rehearsal.rst b/docs/source/user_guide/tutorials/rehearsal.rst index f17a209..49b9a9a 100644 --- a/docs/source/user_guide/tutorials/rehearsal.rst +++ b/docs/source/user_guide/tutorials/rehearsal.rst @@ -16,7 +16,7 @@ Define an actor and a task where some states change: .. code-block:: python - from upstage.utils import waypoint_time_and_dist + from upstage_des.utils import waypoint_time_and_dist class Plane(UP.Actor): speed = UP.State[float]()