Fmdtools

The v.1.3.0 Patch provides a number of changes supporting the increased ability to **simulate more types of scenarios** as well as **optimize** model parameters to both find worst-case scenarios as well as find the best features/response to hazardous scenarios. The major changes are listed below:

1. 'propagate' methods have been refactored in a major way to enable more scenarios to be modelled and enable more outputs to be generated in a consistent way between methods. The major changes include:
1. `propagate.mult_fault` can now take both sequences of faults and **disturbances** which may be passed as a dictionary of times and model variable values to change at a given time (e.g. {4: {flow.value:10}}). This concept of a disturbance is now used throughout, and queried using the new model interface `Model.set_vars`.
2. Results generation in all `propagate` methods is now controlled via the `desired_result` argument, which defaults to "endclasses" (the end-state classification). This parameter can be changed to provide a number of different outputs if desired, such as results graphs, lists of faults, model values at particular times, etc. As a result of this change, single-scenario methods such as `propagate.one_fault` and `propagate.nominal` now only return two values--endresult and mdlhist, rather than endresult, resgraph, and mdlhist, since resgraph is (if the right argument e.g. "bipartite" is sent) provided in endresult.
2. A new `faultsim.search` module has been written enable the optimization of fault scenarios as well as the system architecture/response to these scenarios, including:
1. The `ProblemInterface` class, which can be used to optimize both the parameters and scenarios/response of a system over a single or multiple simulations. Several examples of using this for optimization have furthermore been incorporated in the repository, in `multirotor_example`, `pump_example`, 'tank_example', and `rover_example`.
2. A `DynamicInterface` class, which can be used to optimize a dynamic scenario to bring the system to failure. This enables the interfacing of fmdtools models with adaptive stress testing methods (e.g., in [AdaStress](https://github.com/NASA-SW-VnV/AdaStress.jl)), which is shown in `pump_example/AST_Integration.ipynb`.
3. A variety of examples have been added to demonstrate recently-developed human factors modelling, degradation modelling, and mode sampling capabilities. These are mainly in the `rover_example` folder.

Some additional minor changes include:

- NominalApproach and Sampleapproach now provide tractable __repr__
- Custom Flow classes now throw warnings when custom copy/reset/status methods have not been implemented
- A variety of bugfixes for Components
- End conditions now do not trigger of nominal run of fault simulations (for better history copying)
- `plot.phases` now sets figsize, v_padding, title_padding options consistent with other plot functions
- `update_seed` can now be used to pass new seeds to stochastic models post-instantiation (if desired), and `get_pdf` can in turn provide a pdf value corresponding to the samples from the seed.

The *first major feature* in this patch is a dedicated workflow and methods for saving and loading simulation results. This can now be accomplished in a few ways:

- Using rd.process.save_result(), to save any endclass or mdlhist dictionary (nested or otherwise) as a pkl, csv, or json file.
- pickle is a serialization format, and is thus very fast, but not human-readable. It is also not very secure, and not recommended for files which will be passed on a network
- csv outputs as comma separated values, which are slower and less robust (in terms of data types), but are human-readable (e.g., excel, etc).
- json is similar to csv, but is less human readable.
- Using rd.process.load_result(), to load any saved endclass or mdlhist dictionary.
- Using save_args as an argument in propagate functions. This enables results to automatically be saved during execution, which can be more convenient. It also enables one to (if the "indiv":True argument is passed in multi-scenario methods e.g. approach) save results individually as they are executed (rather than all being saved at the end). This enables some analysis during simulations if desired.
- Tests for each of these are now present in tests/CommonTests (and deployed in test_pump, test_tank and test_pump_stochastic).

The *second major feature* in this patch is the ability to change timesteps used in dynamic behaviors. This can now worked with using:
- Setting the timestep in the function using the option super.__init__(dt=local timestep)
- Setting the timestep using fxn.set_timestep(local_tstep=local timestep)
- Using self.dt in function behavior to increment model behaviors
- Note: one of the above options must be used to run the function individually if using the dt attribute
- Note: self.dt replaces self.tstep and models using tstep at the local level must be re-written
- Resultdisp.graph.exec_order now shows this timestep

*Additional Changes Include:*
- Cost-based functions in resultdisp have been generalized to metrics (meaning, you can pass whatever metric in endclasses you want to use and it will display that, instead of just pulling “cost”). These functions have also been renamed as follows:
- plot.samplecost -> plot.samplemetric
- plot.samplecosts -> plot.samplemetrics
- plot.costovertime -> plot.metricovertime
- tabulate.costovertime -> tabulate.metricovertime
- Fmea functions in resultdisp.tabulate have been revamped around the newly-generated fmea function. This has resulted in:
- The creation of tabulate.fmea, which can now be used to create a variety of fmeas
- grouped by different scenario groups using the group_by option, e.g.:
- functionphase
- mode
- function
- modetype
- times
- fxnclass
- …
- with metrics tabulated as sums, averages, weighted averages, and multiplications, etc.
- Deprecation (but not removal) of tabulate.phasefmea and tabulate.summfmea. Documentation now points users to the fmea function.
- The fmea functions can now tabulate the values of any metric instead of just rate/cost/expected cost
- propagate.nested_approach now additionally returns the apps generated by the process These approaches can be saved using the save_args option.
- Block/FxnBlock:
- More options can be send to FxnBlock.assoc_modes—now the opportunity vector can be defined as a dictionary so that phases are keyed appropriately by the local mode of the function.
- Timers can be associated with Blocks using self.assoc_timers()
- Section dividers now used in plot.nominal/resilience factor comparison
- process.renest_flattenned_hist can now be used to re-nest a flattened results history, while flatten_hist also moved to the resultdisp.process module.
- Memory use of model constructs can now be gotten using:
- rd.process.get_hist_memory gets memory for the entire model history
- propagate functions now warn the user if memory use will go above a predetermined threshold
- Functions/Flows/Models now have get_memory() methods to get memory use
- Title_padding can now be sent to rd.plot. plot.mdlhists can now have legend titles added
- Changes to SampleApproach:
- Can give limit jointphases options to limit the join
- Jointphases can now b
- Various bugfixes
- Changes to NominalApproach
- Non-hashable input arguments can now be passed to param_ranges
- Can now send set arguments to param_ranges
- Bugfixes:
- Propagating any set of multiple faults now returns the nominal information in endclasses/mdlhists (it was missing in several functions)
- Title padding now properly used in plot functions
- Various fixes to staged execution, SampleApproach phase and joint phase sampling, etc.
- Plotting now defaults to "plt.rcParams['pdf.fonttype'] = 42"

- Accommodation of human factors use-case with action sequence graph construct. This enables the use of a state machine in function blocks to specify sequences of behaviors. IT additionally enables this sequence to be visualized for verification purposes.
- Plotting code consolidation of plot.mdlhist and mdlhistvals to plot.mdlhists to create a unified interface
- Accommodation of stochastic modelling use-case via the addition of helper functions for plotting the distribution of multiple metrics on the same plot.

Release encompasses 1-2 years of development work, including;
- Parallel Processing and computational efficiency
- Syntax and model definition improvements
- Graphing/Plotting improvements
- Nested Nominal/Fault sampling improvements
- Modelling of stochastic variables
- ... and many more