update docs and tests

NASA-SW-VnV · Apr 22, 2024 · 2f9abe6 · 2f9abe6
1 parent dab0c91
commit 2f9abe6
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 88 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 ![AdaStress](docs/logo.svg)
 
-AdaStress is a software package that implements the Adaptive Stress Testing (AST) framework, which determines the likeliest failures for a system under test.
+AdaStress is a software package that implements and extends the Adaptive Stress Testing (AST) framework, which determines the likeliest failures for a system under test.
 
 AdaStress provides three primary services:
 - Interfaces between user simulations and the AST framework
@@ -11,7 +11,7 @@ AdaStress provides three primary services:
 
 AdaStress is written in the Julia programming language. If you do not have Julia on your computer, follow [the official instructions](https://julialang.org/downloads/platform) to download the latest version. For information on using Julia, see the [language documentation](https://docs.julialang.org). To download and build the latest version of AdaStress, open the Julia REPL, type `]` to enter the interactive package mode, and enter the command
 ```
-add https://babelfish.arc.nasa.gov/bitbucket/scm/adastress/adastress.git
+add ssh://git@babelfish.arc.nasa.gov:7999/adastress/adastress.git
 ```
 To use the package, enter the command
 ```
@@ -32,8 +32,7 @@ AdaStress provides two basic simulation interfaces, **black-box** and **gray-box
 Your simulation must inherit from the `BlackBox` or `GrayBox` type and implement the methods found in `src/interface/BlackBox.jl` or `src/interface/GrayBox.jl`.
 
 ## Further information
-For more detailed instructions on using AdaStress, see the [complete documentation](./docs/main.md). Example notebooks can be found in the `examples` directory. For background on original AST formulation, see
-> Lee, Ritchie, Ole J. Mengshoel, Anshu Saksena, Ryan W. Gardner, Daniel Genin, Joshua Silbermann, Michael Owen, and Mykel J. Kochenderfer. "Adaptive stress testing: Finding likely failure events with reinforcement learning." Journal of Artificial Intelligence Research 69 (2020): 1165-1201.
+For more detailed instructions on using AdaStress, see the [complete documentation](./docs/main.md). Example notebooks can be found in the `examples` directory. For background on the AST formulation, see the [original paper](https://doi.org/10.1613/jair.1.12190).
 
 ## License
 AdaStress has been released under the NASA Open Source Agreement version 1.3, as detailed [here](LICENSE.pdf).

diff --git a/docs/main.md b/docs/main.md
@@ -4,17 +4,16 @@
 
 ---
 
-- [Maintainers](#maintainers)
-- [Description](#description)
-- [Prerequisites](#prerequisites)
-- [Architecture](#architecture)
-- [Problem setup](#problem-setup)
-- [Interface](#interface)
-- [Serialization interface](#serialization-interface)
-- [Submodule management](#submodule-management)
-- [Solvers](#solvers)
-- [Analysis](#analysis)
-- [Acknowledgements](#acknowledgments)
+[Maintainers](#maintainers)\
+[Description](#description)\
+[Prerequisites](#prerequisites)\
+[Architecture](#architecture)\
+[Problem setup](#problem-setup)\
+[Interface](#interface)\
+[Serialization interface](#serialization-interface)\
+[Solvers](#solvers)\
+[Analysis](#analysis)\
+[Acknowledgements](#acknowledgments)
 
 ---
 
@@ -24,7 +23,7 @@
 
 ## Description
 
-AdaStress is a software package that implements the [adaptive stress testing (AST) framework](https://doi.org/10.1613/jair.1.12190), which determines the likeliest failures for a system under test.
+AdaStress is a software package that implements and extends the [adaptive stress testing (AST) framework](https://doi.org/10.1613/jair.1.12190), which determines the likeliest failures for a system under test.
 
 AdaStress provides three primary services:
 - Interfaces between user simulations and the AST framework
@@ -35,7 +34,7 @@ AdaStress provides three primary services:
 
 AdaStress is written in the Julia programming language. If you do not have Julia on your computer, follow [the official instructions](https://julialang.org/downloads/platform) to download the latest version. For information on using Julia, see the [language documentation](https://docs.julialang.org). To download and build the latest version of AdaStress, open the Julia REPL, type `]` to enter the interactive package mode, and enter the command
 ```
-add https://babelfish.arc.nasa.gov/bitbucket/scm/adastress/adastress.git
+add ssh://git@babelfish.arc.nasa.gov:7999/adastress/adastress.git
 ```
 To use the package, enter the command
 ```
@@ -191,49 +190,6 @@ The serialization capabilities also make it easier to interact with other progra
 
 An `ASTServer` and `ASTClient` can be created separately and configured to exchange a minimal amount of information to enable stress-testing. This exchange can be further encrypted in various ways, in order to obscure the system under test from the stress-testing agent. For an example of serialized stress-testing, see the notebooks in `examples/pedestrian`.
 
-## Submodule management
-
-The submodule manager allows optional and experimental features with heavy dependencies to be made available without increasing the loading time of the base package. The user can selectively enable and disable these submodules as needed. In the background, the submodule manager maintains an internal project environment with a minimal set of necessary dependencies, avoiding the need to load unused packages.
-
-This system is made necessary by certain limitations of the language, which does not currently support optional dependencies. A common solution involves creating multiple separate packages to extend a base package; however, we consider this approach somewhat of an anti-pattern, and have chosen not to employ it here. In future versions of AdaStress, the submodule system may be removed if a suitable alternative is possible.
-
-### Using submodules
-
-Submodules are managed through the following API:
-
-> - **`AdaStress.submodules()`**
-> List all available submodules.
-> - **`AdaStress.enabled()`**
-> List enabled submodules.
-> - **`AdaStress.enable(submodule)`**
-> Enable submodule(s). Accepts string or vector of strings. With zero arguments defaults to all associated submodules. Takes effect immediately.
-> - **`AdaStress.disable(submodule)`**
-> Disable submodule(s). Accepts string or vector of strings. With zero arguments defaults to all enabled submodules. Takes effect after Julia restart.
-> - **`AdaStress.load()`**
-> Load enabled submodules (necessary after Julia restart). Takes effect immediately.
-> - **`AdaStress.clean()`**
-> Forcibly remove temporary environment, purging all enabled submodules. Only necessary if submodule manager is corrupted and `disable` cannot restore functionality. Takes effect after Julia restart.
-
-Enabling a submodule can take several seconds, particularly the first time. Due to current limitations of the language, previously enabled submodules cannot be automatically loaded when a new Julia session is launched. The user should use the `load` command for this, as in the following example. In the first session, it is necessary to run
-
-> ```
-> julia> using AdaStress
-> julia> AdaStress.enable("SoftActorCritic")
-> ```
-while in later sessions, the user may simply run
-> ```
-> julia> using AdaStress
-> julia> AdaStress.load()
-> ```
-
-### Multiprocessing
-
-Due to current bugs in the language, many processes related to code loading and environment management are not truly atomic. This can lead to problems when submodules are used in multiprocessing, as occurs with policy-value verification analysis. In such cases, care should be taken when invoking the submodule manager API asynchronously. For an example of loading submodules on multiple processes, see the notebook `examples/pvv`.
-
-### Creating submodules
-
-Custom submodules are essentially regular Julia packages that reside within the AdaStress directory tree, complete with a UUID and `Project.toml` file. Submodules are associated with AdaStress via the `exclude` command, similarly to how source files are associated via `include`.
-
 ## Solvers
 
 A solver object is a standalone entity representing an algorithm and its parameters. A solver can be applied to an `ASTMDP` or a function that generates an `ASTMDP`, producing a `Result` object, as in
@@ -295,8 +251,6 @@ Q-learning is a classic reinforcement learning algorithm that uses a table-based
 
 #### Soft actor-critic
 
->This feature is contained in a submodule, and must be explicitly enabled.
-
 Soft actor-critic (SAC) is a deep reinforcement learning algorithm that simultaneously learns a value function and a policy for the `ASTMDP`. Both take the form of neural networks, which can be used to generate failures online in real-time or analyze system properties offline. SAC offers the following tunable parameters:
 
 | Parameter | Type | Default | Description |
@@ -344,8 +298,6 @@ The analysis module provide methods to further analyze results.
 
 ### Policy-value verification
 
->This feature is contained in a submodule, and must be explicitly enabled.
-
 Policy-value verification (PVV) is an experimental method of analyzing the output of a global solver. It assembles the policy network and value network (or ensemble of value networks) into a single value function over the state space. Then, given a set condition on the value function, the algorithm uses an adaptive refinement process to classify regions of state space that provably satisfy the condition, violate the condition, or are unprovable at the given tolerance.
 
 As a matter of ongoing research, requirements concerning the safety of the system can be linked to conditions on the value function. For instance, a requirement that the possibility of failure not exceed $10^{-9}$ from a set of initial states (given some modeled environmental stochasticity) translates to a constraint on the value function. The validity and practicality of this analysis is largely dependent on the learning process and is still uncertain. Nonetheless, the approach can currently generate *approximate* artifacts that may be useful for casual and nonrigorous analysis of system performance. 
@@ -358,4 +310,4 @@ For an example of a problem analyzed with PVV, see the notebook `examples/pvv`.
 
 The adaptive stress testing framework was proposed and developed by Ritchie Lee during his PhD under the supervision of Prof. Mykel Kochenderfer (Stanford University). Ritchie directed the creation of AdaStress and was instrumental in shaping our particular approach to this problem.
 
-Some of the basic nomenclature in AdaStress is borrowed from the package `POMDPStressTesting.jl`, namely the `GrayBox` and `BlackBox` terminology. Note that the usage and interpretation of these terms differs between the packages. Code that is compatible with one package cannot immediately be used with the other without modification.
+Some of the basic nomenclature in AdaStress is borrowed from the package `POMDPStressTesting.jl`, namely the `GrayBox` and `BlackBox` terminology. Note that the usage and interpretation of these terms differs between the packages. Code that is compatible with one package cannot immediately be used with the other without modification.
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -32,28 +32,6 @@ using AdaStress
 using NBInclude
 using Test
 
-@testset "Interface" begin
-    @test AdaStress.GrayBox <: Interface.AbstractSimulation
-end
-
-@testset "Solvers" begin
-    @test begin
-        AdaStress.SoftActorCritic.MLPActorCritic(1, 1, [-1.0], [1.0]) isa AdaStress.GlobalResult
-    end
-end
-
-#=
-@testset "Analysis" begin
-    @test begin
-        AdaStress.enable("PolicyValueVerification")
-        using .PolicyValueVerification
-        ac = SoftActorCritic.MLPActorCritic(1, 1, [-1.0], [1.0])
-        SoftActorCritic.to_cpu!(ac)
-        nnet = PolicyValueVerification.policy_network(ac; act_mins=[-1.0], act_maxs=[1.0])
-        nnet isa PolicyValueVerification.ExtendedNetwork
-    end
-end
-
 # Example notebooks to be tested (cells beginning with `# autoskip` are not executed)
 envs = ["walk1d", "walk2d"]
 
@@ -68,4 +46,3 @@ for env in envs
         end
     end
 end
-=#