fmdtools 2.2.3__tar.gz → 2.3.1__tar.gz

{fmdtools-2.2.3 → fmdtools-2.3.1}/LICENSE

@@ -1,4 +1,4 @@
-fmdtools version 2.2.3
+fmdtools version 2.3.1
 ---------------------------
                                  Apache License
                            Version 2.0, January 2004

{fmdtools-2.2.3 → fmdtools-2.3.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: fmdtools
-Version: 2.2.3
+Version: 2.3.1
 Summary: System resilience modelling, simulation, and assessment in Python
 Author: fmdtools Developers
 Maintainer-email: Daniel Hulse <daniel.e.hulse@nasa.gov>
-License: fmdtools version 2.2.3
+License: fmdtools version 2.3.1
         ---------------------------
                                          Apache License
                                    Version 2.0, January 2004
@@ -253,10 +253,19 @@ Requires-Dist: matplotlib>=3.7.0
 Requires-Dist: pandas[all]
 Requires-Dist: ordered-set
 Requires-Dist: dill
-Requires-Dist: recordclass==0.23.1
+Requires-Dist: recordclass==0.24
 Requires-Dist: pytest
 Requires-Dist: graphviz
 Requires-Dist: shapely>=2.0
+Provides-Extra: examples
+Requires-Dist: deap; extra == "examples"
+Requires-Dist: pymoo; extra == "examples"
+Requires-Dist: scikit-learn; extra == "examples"
+Requires-Dist: multiprocess; extra == "examples"
+Requires-Dist: pathos; extra == "examples"
+Requires-Dist: adjustText; extra == "examples"
+Provides-Extra: all
+Requires-Dist: fmdtools[examples]; extra == "all"
 Dynamic: license-file
 
 [![fmdtools logo - titanic](/docs-source/figures/logo/logo-titanic.png)](https://github.com/nasa/fmdtools)
@@ -355,19 +364,24 @@ For development as well as interactive use of tutorials and models, we reccomend
 For this installation, fmdtools can be downloaded from the [fmdtools github repository](https://github.com/nasa/fmdtools/) using:
 
 ```
+   cd /path/to/fmdtools
    git clone https://github.com/nasa/fmdtools.git
 ```
 
 This may then be installed using:
 
 ```
-   pip install -e "/path/to/fmdtools" 
+   pip install -e .[all] --group dev
 ```
 
-Note that this version reflects the latest version on the ``main`` git branch along with any local changes. To use a particular version of ``fmdtools`` you can checkout the tag corresponding to the version you want, e.g.:
+Which will install both fmdtools as well as examples (`[all]` option) as well as testing and development dependencies (`--group dev` option)
+
+More guidance on development installations is provided in [How to Contribute](https://nasa.github.io/fmdtools/docs-source/Contributions.html#how-to-contribute)
+
+Note that this version reflects the latest version on the ``main`` git branch along with any local changes. To use a particular version of ``fmdtools`` in the context of a development install you can checkout the tag corresponding to the version you want, e.g.:
 
 ```
-   git checkout v2.2.3
+   git checkout v2.3.1
 ```
 
 
@@ -447,10 +461,9 @@ One `fmdtools` is installed, you should be able to run:
 import fmdtools
 ```
 
-To check the version of fmdtools, you can run the following:
+To check the version of fmdtools, you can check:
 ```
-import importlib.metadata
-importlib.metadata.version("fmdtools")
+fmdtools.__version__
 ```
 which should return the current version of fmdtools.
 
@@ -505,8 +518,8 @@ To cite a particular version of the fmdtools, you may use:
   author = {{NASA}},
   title = {fmdtools},
   url = {https://github.com/nasa/fmdtools},
-  version = {2.2.3},
-  date = {2025-12-4},
+  version = {2.3.1},
+  date = {2025-12-19},
 }
 ```
 

{fmdtools-2.2.3 → fmdtools-2.3.1}/README.md

@@ -94,19 +94,24 @@ For development as well as interactive use of tutorials and models, we reccomend
 For this installation, fmdtools can be downloaded from the [fmdtools github repository](https://github.com/nasa/fmdtools/) using:
 
 ```
+   cd /path/to/fmdtools
    git clone https://github.com/nasa/fmdtools.git
 ```
 
 This may then be installed using:
 
 ```
-   pip install -e "/path/to/fmdtools" 
+   pip install -e .[all] --group dev
 ```
 
-Note that this version reflects the latest version on the ``main`` git branch along with any local changes. To use a particular version of ``fmdtools`` you can checkout the tag corresponding to the version you want, e.g.:
+Which will install both fmdtools as well as examples (`[all]` option) as well as testing and development dependencies (`--group dev` option)
+
+More guidance on development installations is provided in [How to Contribute](https://nasa.github.io/fmdtools/docs-source/Contributions.html#how-to-contribute)
+
+Note that this version reflects the latest version on the ``main`` git branch along with any local changes. To use a particular version of ``fmdtools`` in the context of a development install you can checkout the tag corresponding to the version you want, e.g.:
 
 ```
-   git checkout v2.2.3
+   git checkout v2.3.1
 ```
 
 
@@ -186,10 +191,9 @@ One `fmdtools` is installed, you should be able to run:
 import fmdtools
 ```
 
-To check the version of fmdtools, you can run the following:
+To check the version of fmdtools, you can check:
 ```
-import importlib.metadata
-importlib.metadata.version("fmdtools")
+fmdtools.__version__
 ```
 which should return the current version of fmdtools.
 
@@ -244,8 +248,8 @@ To cite a particular version of the fmdtools, you may use:
   author = {{NASA}},
   title = {fmdtools},
   url = {https://github.com/nasa/fmdtools},
-  version = {2.2.3},
-  date = {2025-12-4},
+  version = {2.3.1},
+  date = {2025-12-19},
 }
 ```
 

{fmdtools-2.2.3 → fmdtools-2.3.1}/examples/__init__.py

@@ -15,4 +15,4 @@ CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
 """
 
-__all__ = ['asg_demo', 'eps', 'multirotor', 'pump', 'rover', 'tank', 'taxiway']
+__all__ = ['asg_demo', 'eps', 'multirotor', 'pump', 'rover', 'tank', 'taxiway' 'airspacelib']

fmdtools-2.3.1/examples/airspacelib/__init__.py

@@ -0,0 +1,22 @@
+"""
+Airspace library.
+
+Copyright © 2024, United States Government, as represented by the Administrator
+of the National Aeronautics and Space Administration. All rights reserved.
+
+The "Fault Model Design tools - fmdtools version 2" software is licensed
+under the Apache License, Version 2.0 (the "License"); you may not use this
+file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE/2.0. 
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+"""
+
+import examples.airspacelib.base as base
+import examples.airspacelib.contingencymanagement as contingencymanagement
+import examples.airspacelib.wildfireresponse as wildfireresponse
+
+__all__ = ['base', 'contingencymanagement', 'wildfireresponse']

fmdtools-2.3.1/examples/airspacelib/base/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""
+Base packages for the Airspace Library.
+
+Copyright © 2024, United States Government, as represented by the Administrator
+of the National Aeronautics and Space Administration. All rights reserved.
+
+The "Fault Model Design tools - fmdtools version 2" software is licensed
+under the Apache License, Version 2.0 (the "License"); you may not use this
+file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE/2.0. 
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+"""
+
+import examples.airspacelib.base.aircraft as aircraft
+import examples.airspacelib.base.parameter as parameter
+import examples.airspacelib.base.state as state
+import examples.airspacelib.base.arch as arch
+
+__all__ = ['aircraft', 'parameter', 'state', 'arch']

fmdtools-2.3.1/examples/airspacelib/base/aircraft.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""
+Base aircraft for use in Airspace Library.
+
+Copyright © 2024, United States Government, as represented by the Administrator
+of the National Aeronautics and Space Administration. All rights reserved.
+
+The "Fault Model Design tools - fmdtools version 2" software is licensed
+under the Apache License, Version 2.0 (the "License"); you may not use this
+file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE/2.0. 
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+"""
+from fmdtools.define.block.function import Function
+
+from examples.airspacelib.base.state import AircraftState
+from examples.airspacelib.base.parameter import AircraftParameter
+
+
+class BaseAircraft(Function):
+    """Base Aircraft function to be used by other models."""
+
+    __slots__ = ()
+    container_s = AircraftState
+    container_p = AircraftParameter
+
+    def indicate_at_goal(self):
+        """Indicate whether the aircraft is at its goal location."""
+        return self.s.at_goal()
+
+    def indicate_in_range(self):
+        """Indicate whether the aircraft is in range of its goal location."""
+        return self.s.in_range()
+
+    def fly_to_goal(self):
+        """Fly to a pre-determined goal."""
+        if not self.indicate_at_goal():
+            self.s.update_position(maxvel=self.p.max_speed)
+            dist = self.s.calc_dist_to_travel()
+            self.s.inc(fuel_status=-dist/self.p.max_range)
+
+
+if __name__ == "__main__":
+    ba = BaseAircraft()

fmdtools-2.3.1/examples/airspacelib/base/aircraftarchitecture.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+"""
+Combined aircraft architecture with all of the subfunctions in /arch.
+
+Copyright © 2024, United States Government, as represented by the Administrator
+of the National Aeronautics and Space Administration. All rights reserved.
+
+The "Fault Model Design tools - fmdtools version 2" software is licensed
+under the Apache License, Version 2.0 (the "License"); you may not use this
+file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE/2.0. 
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+"""
+from fmdtools.define.architecture.function import FunctionArchitecture
+from fmdtools.define.architecture.function import FunctionArchitectureGraph
+from fmdtools.define.container.parameter import Parameter
+import fmdtools.sim.propagate as prop
+
+
+from examples.airspacelib.base.arch.flows import Trajectories, Force, Electricity
+from examples.airspacelib.base.arch.flows import AircraftEnvironment
+from examples.airspacelib.base.arch.aviate import Aviate
+from examples.airspacelib.base.arch.controlflight import ControlFlight
+from examples.airspacelib.base.arch.storeee import StoreAndSupplyElectricity
+from examples.airspacelib.base.arch.perceiveenvironment import PerceiveEnvironment
+from examples.airspacelib.base.arch.holdpayload import HoldPayload
+
+
+class AircraftArchParameter(Parameter):
+    """Overall Parameter Defining the AircraftArchitecture."""
+
+    flightplan: tuple = ((0.0, 0.0), (25.0, 25.0))
+    height: float = 25.0
+
+
+class AircraftArchitecture(FunctionArchitecture):
+    """
+    Overall drone architecture.
+
+    Involves flows:
+        - force: the flow of force between physical components
+        - electricity: the flow of electrical energy from the power supply to functions
+        - trajectories: the 3d position and velocity of the aircraft
+        - environment: the environment the aircraft inhabits and interacts with
+    And functions:
+        - control_flight : flight planning and control
+        - aviate : the function that moves the drone in the x/y/z
+        - store_and_supply_ee : the aircraft power supply/battery
+        - perceive_environment : drone perception and localization
+        - hold_payload : the structure of the drone
+    """
+
+    __slots__ = ()
+    container_p = AircraftArchParameter
+
+    def init_architecture(self, **kwargs):
+        """Initialize the architecture of the aircraft."""
+        self.add_flow('force', Force)
+        self.add_flow('electricity', Electricity)
+        self.add_flow('trajectories', Trajectories)
+        self.add_flow('environment', AircraftEnvironment)
+
+        self.add_fxn('control_flight', ControlFlight,
+                     'trajectories', 'force', 'electricity', 'environment',
+                     s={'flightplan': self.p.flightplan, 'height': self.p.height})
+        self.add_fxn('aviate', Aviate,
+                     'trajectories', 'force', 'electricity', 'environment')
+        self.add_fxn('store_and_supply_ee', StoreAndSupplyElectricity,
+                     'force', 'electricity')
+        self.add_fxn('perceive_environment', PerceiveEnvironment,
+                     'environment', 'force', 'electricity', 'trajectories')
+        self.add_fxn('hold_payload', HoldPayload, 'trajectories', 'force')
+
+    def classify(self, **kwargs):
+        """Classify the simulation results."""
+        return {'faultmodes': {*self.return_faultmodes()}}
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod(verbose=True)
+
+    t = Trajectories()
+    t.create_local('perc_traj')
+    cf = ControlFlight(trajectories=t)
+    av = Aviate(trajectories=t)
+
+    cf.dynamic_behavior()
+    cf.des_traj.s
+    av.dynamic_behavior()
+    av.trajectories.s
+
+    cf.dynamic_behavior()
+    cf.des_traj.s
+    av.dynamic_behavior()
+    av.trajectories.s
+
+    da = AircraftArchitecture(p={'flightplan':((0.0, 0.0), (25.0, 0.0), (0.0, 25.0), (25.0, 25.0))})
+    fg = FunctionArchitectureGraph(da)
+    fg.draw()
+
+    res, hist = prop.nominal(da)
+
+    res, hist = prop.one_fault(da, 'store_and_supply_ee', 'depletion', 7, to_return=['classify', 'graph'])
+    res.store_and_supply_ee_depletion_t7.tend.graph.draw()
+
+    hist.plot_trajectories('trajectories.s.x', 'trajectories.s.y')
+    hist.plot_trajectories('trajectories.s.x',
+                           'trajectories.s.y',
+                           'trajectories.s.z',
+                           time_groups='nominal', time_ticks=1.0)
+
+    hist.plot_line('flows.electricity.s.charge',
+                   'fxns.control_flight.m.mode',
+                   'fxns.aviate.m.mode')

fmdtools-2.3.1/examples/airspacelib/base/arch/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+Base architecture components for the Airspace library.
+
+Copyright © 2024, United States Government, as represented by the Administrator
+of the National Aeronautics and Space Administration. All rights reserved.
+
+The "Fault Model Design tools - fmdtools version 2" software is licensed
+under the Apache License, Version 2.0 (the "License"); you may not use this
+file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE/2.0. 
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+"""
+
+import examples.airspacelib.base.arch.aviate as aviate
+import examples.airspacelib.base.arch.controlflight as controlflight
+import examples.airspacelib.base.arch.flows as flows
+import examples.airspacelib.base.arch.holdpayload as holdpayload
+import examples.airspacelib.base.arch.perceiveenvironment as perceiveenvironment
+import examples.airspacelib.base.arch.storeee as storeee
+
+__all__ = ['aviate', 'controlflight', 'flows', 'holdpayload', 'perceiveenvironment',
+           'storeee']

fmdtools-2.3.1/examples/airspacelib/base/arch/aviate.py

@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""
+Aviate functionality.
+
+Copyright © 2024, United States Government, as represented by the Administrator
+of the National Aeronautics and Space Administration. All rights reserved.
+
+The "Fault Model Design tools - fmdtools version 2" software is licensed
+under the Apache License, Version 2.0 (the "License"); you may not use this
+file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE/2.0. 
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+"""
+from fmdtools.define.container.mode import Mode
+from fmdtools.define.block.function import Function
+
+from examples.airspacelib.base.arch.flows import Trajectories, Force, Electricity
+from examples.airspacelib.base.arch.flows import AircraftEnvironment
+import numpy as np
+
+class AviateMode(Mode):
+    """Aviate function modes."""
+
+    opermodes = ('flight', 'idle', 'falling')
+    mode: str = "idle"
+    fault_crash = ()
+
+
+class Aviate(Function):
+    """
+    Function that moves the drone within the environment.
+
+    Examples
+    --------
+    >>> t = Trajectories()
+    >>> t.s.put(z=100.0, goal_z=100.0, dz=0.0, dx=10.0)
+    >>> des_traj = t.create_local("des_traj")
+    >>> av = Aviate(trajectories=t)
+    >>> av.static_behavior()
+    >>> av.dynamic_behavior()
+    >>> av.trajectories.s.x
+    10.0
+    >>> av.trajectories.des_traj.s.put(dx=0.0, dy=10.0)
+    >>> av.static_behavior()
+    >>> av.dynamic_behavior()
+    >>> av.trajectories.s.y
+    10.0
+    """
+
+    __slots__ = ('trajectories', 'force', 'electricity', 'environment')
+
+    flow_trajectories = Trajectories
+    flow_force = Force
+    flow_electricity = Electricity
+    flow_environment = AircraftEnvironment
+    container_m = AviateMode
+
+    def static_behavior(self):
+        """Overall static behavior of drone (determines modes based on states)."""
+        if self.force.s.contact_support >= 10.0:
+            self.m.add_fault('crash')
+
+        if self.trajectories.s.z > 0.0:
+            if self.electricity.s.voltage_high <= 0.0:
+                self.m.set_mode('falling')
+            else:
+                self.m.set_mode('flight')
+        else:
+            if self.electricity.s.voltage_high > 0.0:
+                if not self.trajectories.des_traj.s.same(dx=0.0, dy=0.0):
+                    self.m.add_fault('crash')
+                    self.m.set_mode('idle')
+                elif not self.trajectories.des_traj.s.dz <= 0.0:
+                    self.m.set_mode('flight')
+                else:
+                    self.m.set_mode('idle')
+            else:
+                self.m.set_mode('idle')
+
+        if self.m.in_mode("falling", "crash"):
+            self.falling_behavior()
+        elif self.m.in_mode('flight'):
+            self.flight_behavior()
+        elif self.m.in_mode("idle"):
+            self.idle_behavior()
+
+    def dynamic_behavior(self):
+        """Overall dynamic behavior of the drone (flight, falling, and idle)."""
+        self.trajectories.s.increment_position()
+        self.trajectories.s.limit(z=(0.0, np.inf))
+
+    def flight_behavior(self):
+        """
+        Behavior when the drone is flying in the air.
+
+        The trajectory increments to a new location determined by the direction and
+        distance of the desired trajectory.
+        """
+        self.trajectories.s.assign(self.trajectories.des_traj.s, 'dx', 'dy', 'dz')
+        self.electricity.s.current_high = 1.0
+        self.force.s.put(lift_support=1.0)
+
+    def falling_behavior(self):
+        """
+        Behavior when falling.
+
+        The drone falls to the ground, removing all support to the drone.
+        """
+        if self.trajectories.s.z > 0.0:
+            #self.trajectories.s.assign(self.trajectories.des_traj.s, 'dx', 'dy')
+            self.trajectories.s.dz = -self.trajectories.s.z
+            self.force.s.put(lift_support=0.0)
+        else:
+            self.idle_behavior()
+
+    def idle_behavior(self):
+        """Behavior when not moving and grounded."""
+        self.trajectories.s.put(dx=0.0, dy=0.0, dz=0.0)
+        self.force.s.put(lift_support=0.0)
+        self.electricity.s.current_high = 0.0
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod(verbose=True)
+
+    av = Aviate()