Initial commit under X11 license

Co-Authored-By: Christine Serres <[email protected]>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,72 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+Read the instructions and fill out your responses at the bottom.
+
+## Instructions
+
+### Description
+A clear and concise description of what the bug is.
+
+### Reproducibility
+
+Describe the exact steps which reproduce the problem in as many details as possible. For example, start by explaining how you started the computing environment or which command exactly you used in the terminal. When listing steps, don't just say what you did, but explain how you did it.
+
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+### Expectation
+
+A clear and concise description of what you expected to happen.
+
+### Recency
+
+Did the problem start happening recently (e.g. after updating to a new version) or was this always a problem?
+
+### Files
+
+If the problem is related to working with files (e.g. opening and editing files), does the problem happen for all files and projects or only some? Does the problem happen only when working with local or remote files (e.g. on network drives), with files of a specific type (e.g. only JavaScript or Python files), with large files or files with very long lines, or with files in a specific encoding? Is there anything else special about the files you are using?
+
+### Environment
+
+- OS: [e.g. Windows 10, Ubuntu 18.04]
+- Programming language and version: [e.g. MATLAB 2019a, Julia 1.1.1]
+- Computing environment: [e.g. MATLAB, VS Code]
+- Are you running in a virtual machine" [e.g. yes, no]
+- Compiler (if applicable): [e.g. g++, cl]
+
+### Screenshots
+
+Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use this [tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and this [tool](https://github.com/colinkeenan/silentcast) or this [tool](https://github.com/GNOME/byzanz) on Linux.
+
+### Additional context
+
+Add any other context about the problem here.
+
+## FILL ME OUT
+
+### Description
+
+### Reproducibility
+
+### Expectation
+
+### Recency
+
+### Files
+
+### Environment
+
+### Screenshots
+
+### Additional

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,38 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[ENHANCEMENT]"
+labels: enhancement
+assignees: ''
+
+---
+
+## Instructions
+
+Read the instructions and fill out your responses at the bottom.
+
+### Relation
+
+Is your feature request related to a problem? Please describe. Please provide a clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+### Description
+
+A clear and concise description of what you want to happen.
+
+### Alternatives
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional context
+
+Add any other context or screenshots about the feature request here.
+
+## FILL ME OUT
+
+### Relation
+
+### Description
+
+### Alternatives
+
+### Additional

.gitignore

@@ -0,0 +1,52 @@
+# MATLAB
+# Windows default autosave extension
+*.asv
+
+# OSX / *nix default autosave extension
+*.m~
+
+# Compiled MEX binaries (all platforms)
+# *.mex*
+
+# Packaged app and toolbox files
+*.mlappinstall
+*.mltbx
+
+# Generated helpsearch folders
+helpsearch*/
+
+# Simulink code generation folders
+slprj/
+sccprj/
+
+# Matlab code generation folders
+codegen/
+
+# Simulink autosave extension
+*.autosave
+
+# Simulink cache files
+*.slxc
+
+# Octave session info
+octave-workspace
+*.zip
+*.mexw64
+
+# MS Office Temp
+~*.doc
+~*.docx
+~*.tmp
+
+# Directory specific
+Tests/**/*.mat
+Tests/Generated_Encounters/**/*.txt
+Tests/Code_Coverage/**/*.png
+Tests/Code_Coverage/**/*.jpg
+Tests/Test_Outputs/*/*.fig
+Tests/Test_Outputs/**/*.txt
+
+# Web specific (used by in Code_Coverage)
+*.js
+*.html
+*.css

Encounter_Generation_Tool/EncounterModelEvents.m

@@ -0,0 +1,68 @@
+% Copyright 2018 - 2020, MIT Lincoln Laboratory
+% SPDX-License-Identifier: X11
+%%
+classdef EncounterModelEvents < handle
+    %This class defines the encounter model events, which are times when a
+    %change in the aircraft dynamics occurs
+    %%
+    properties (GetAccess = 'public', SetAccess = 'public')
+        time_s = 0; % seconds
+        verticalRate_fps = 0; % feet per second
+        turnRate_radps = 0; % radians per second
+        longitudeAccel_ftpss = 0; % feet per second squared
+    end % end properties
+
+    properties (Dependent=true)
+        event % The event matrix = [ time_s(:) verticalRate_fps(:) turnRate_radps(:) longitudeAccel_ftpss(:)]
+    end
+    methods
+        function this = set.event( this, eventMatrix )
+            assert( size( eventMatrix,2 ) == 4 );
+            this.time_s = eventMatrix(:,1);
+            this.verticalRate_fps = eventMatrix(:,2);
+            this.turnRate_radps = eventMatrix(:,3);
+            this.longitudeAccel_ftpss = eventMatrix(:,4);
+        end
+        function eventMatrix = get.event( this )            
+            eventMatrix = [this.time_s(:) this.verticalRate_fps(:) this.turnRate_radps(:) this.longitudeAccel_ftpss(:)];
+            % eventMatrix always needs to have at least one row
+            if( size( eventMatrix, 1 ) == 0 )
+                eventMatrix = [ 0 0 0 0 ];
+            end
+        end
+    end
+
+    %%
+    methods(Access = 'public')
+        function obj = EncounterModelEvents (varargin)  
+            % Parse Inputs
+            p = inputParser;
+            if any(strcmp(varargin,'event'))
+                addParamValue(p,'event',[0 0 0 0],@isnumeric);
+            else % If event matrix is being passed, ignore control individual properties
+                addParamValue(p,'time_s',obj.time_s,@isnumeric);
+                addParamValue(p,'verticalRate_fps',obj.verticalRate_fps,@isnumeric);
+                addParamValue(p,'turnRate_radps',obj.turnRate_radps,@isnumeric);
+                addParamValue(p,'longitudeAccel_ftpss',obj.longitudeAccel_ftpss,@isnumeric);
+            end   
+            parse(p,varargin{:});
+
+            % Set Properties
+            fieldsSet = intersect( fieldnames(p.Results), fieldnames(obj) );  
+            for i = 1:1:numel(fieldsSet)
+                obj.(fieldsSet{i}) = p.Results.(fieldsSet{i});
+            end
+
+            % Error Checking
+            assert(all((size(obj.time_s) == size(obj.verticalRate_fps)) == (size(obj.turnRate_radps) == size(obj.longitudeAccel_ftpss))),'Sizes of time_s, verticalRate_fps, turnRate_radps, longitudeAccel_ftpss are not equal');
+        end % End constructor
+
+        function event = createEventMatrix(obj,filename)
+            assert(ischar(filename),'Second input must be a char'); % Error checking
+            event = obj.event';% Format according to how Logic and Response: Nominal Trajectory block is expecting
+            save(filename, 'event'); % Save .mat file for block
+        end
+
+    end % End methods
+
+end %End classdef

Encounter_Generation_Tool/README.md

@@ -0,0 +1,44 @@
+# Encounter Generation Tool Code
+
+MATLAB code that constitutes the encounter generation tool.
+
+- [Encounter Generation Tool Code](#encounter-generation-tool-code)
+  - [Overview](#overview)
+  - [3rd Party Code](#3rd-party-code)
+  - [Distribution Statement](#distribution-statement)
+
+## Overview
+
+The files in the following table are part of the Encounter Generation Tool. Note that some of the software listed is found in [`em-model-manned-bayes`](https://github.com/Airspace-Encounter-Models/em-model-manned-bayes) or [`em-core`](https://github.com/Airspace-Encounter-Models/em-core).
+
+| Functionality  | File Name | Description |
+| ------------- | ------------- |------------- |
+| Run scripts for generating encounters | <ul><li>`generateDAAEncounterSet.m`</li><li>`ini2struct.m`</li><li>`load_constants.m`</li></ul>  | `generateDAAEncounterSet.m` takes in an .INI parameter file and generates a set of encounters with the characteristics specified in the parameter file. <br><br> `ini2struct.m` is a helper function for reading in parameters in the .INI file. <br><br> `load_constants.m` defines common constants for unit conversions |
+| Input validation   | <ul><li>`checkEncounterModelInputs.m`</li><li>`checkINIInputs.m`</li></ul>   | `checkEncounterModelInputs.m` validates user-modified Uncorrelated Encounter Model characteristics and throws an error if there are any improperly formatted variables. <br><br> `checkINIInputs.m` validates the parameters in the .INI file and throws an error if any values are invalid. |
+| Sampling from the Lincoln Uncorrelated Encounter Model  | <ul><li>`asub2ind.m`</li><li>`bn_dirichlet_prior.m`</li><li>`bn_sample.m`</li><li>`bn_sort.m`</li><li>`dbn_hierarchical_sample.m`</li><li>`dbn_sample.m`</li><li>`dediscretize.m`</li><li>`em_read.m`</li><li>`EncounterModelEvents.m`</li><li>`resample_events.m`</li><li>`select_random.m`</li><li>`uncor_v2p1.txt`</li></ul> | These files are used to sample trajectories from the Uncorrelated Encounter Model. <br><br>`em_read.m` is used to parse `uncor_v2p1.txt`, which contains the Uncorrelated Encounter Model. The Uncorrelated Encounter Model parameters can be tuned to change the behavior of the intruder: see the Example_Inputs [README](../Example_Inputs/README.md#encounter-model-files) for more information. See this [paper](https://apps.dtic.mil/sti/pdfs/ADA589697.pdf) for an explanation of the parameters. <br><br>`EncounterModelEvents.m` creates an event matrix for the intruder trajectory (containing the times when updates in vertical rate/turn rate/acceleration occur). <br><br> All other files are helper functions for `dbn_hierarchical_sample.m`, which is used to sample a vector of initial values (geographic region, airspace class, altitude layer, airspeed, acceleration, vertical rate, turn rate), and a matrix of events (time, vertical rate, turn rate, acceleration) for every encounter. This [paper]( https://apps.dtic.mil/sti/pdfs/ADA589697.pdf) provides a description of how samples are generated from the Uncorrelated Encounter Model. |
+| Sampling from a set of trajectories | <ul><li>`ecef_to_enu.m`</li><li>`geod_to_ecef.m`</li><li>`sampleTrajectory.m`</li><li>`upsampleTrajectory.m`</li></ui> | `sampleTrajectory.m` samples one trajectory from a set of user-defined trajectories. The directory containing the trajectories must be specified in the .INI file. Tracks may be sampled uniformly or the sampling process may be weighted so that longer tracks are more likely to be sampled than shorter tracks. Filtering can also be applied at this step such that tracks that do not satisfy minimum/maximum airspeed/altitude limits are rejected. See the Example_Inputs [README](../Example_Inputs/README.md#trajectory-files) for the expected format of these trajectories.<br><br>`geod_to_ecef.m` and `ecef_to_enu.m` are used to convert the trajectories from lat/lon to x/y (east and north). The encounters are initialized and output in terms of east and north. <br> <br> `upsampleTrajectory.m` is used to convert the input trajectories from 1 Hz to 10 Hz.|
+| Initializing encounters   | <ul><li>`initializeUncorrelatedEncounter.m`</li><li>`UncorEncounterParameters.m`</li></ul>  | `initializeUncorrelatedEncounter.m` shifts and rotates the sampled ownship and intruder trajectories so that the encounter has the sampled values of HMD and VMD at CPA. <br><br> `UncorEncounterParameters.m` is a class that contains parameters used to initialize uncorrelated encounters. |
+| Simulating Dynamics  | <ul><li>`minmax.h`</li><li>`run_dynamics_fast.c`</li><li>`run_dynamics_fast.mexa64`. `run_dynamics_fast.mexw64`, or `run_dynamics_fast.mexmaci64` (generated by user - see the Encounter Generation Tool [README](../README.md#mex))</li></ui>  | `run_dynamics_fast.c` is an implementation of the DEGAS dynamics in C. The mexed version of this function (`run_dynamics_fast.mexa64` for Linux,  `run_dynamics_fast.mexw64` for Windows, or  `run_dynamics_fast.mexmaci64` for Mac) is used by the Encounter Generation Tool to convert sampled encounter model events into trajectories. The dynamics constraints in `run_dynamics_fast.c` are the same as the constraints in DEGAS. Note that the user will need to mex `run_dynamics_fast.c` if any changes are made to the file (e.g., to change the constraints). <br><br> `minmax.h` is a helper function used by the dynamics.|
+| Computing metadata   | <ul><li>`computeEncProperties.m`</li><li>`getCPAMetrics.m`</li><li>`getNominalManeuvers.m`</li></ui>  |`computeEncProperties.m` outputs encounter metadata including intruder/ownship height and speed at TCA, encounter weight, and encounter duration. <br><br>The function calls `getCPAMetrics.m` to compute HMD, VMD, TCA, and whether an NMAC occurs. <br><br> The function also calls `getNominalManeuvers.m` to determine whether the ownship/intruder has a nominal maneuver before TCA. A nominal maneuver is any horizontal or vertical maneuver that is in the generated ownship/intruder trajectory. These are distinct from maneuvers issued by a DAA system.|
+| Outputting Encounters (Waypoints or Events)  | <ul><li>`compute_delta_heading.m`</li><li>`readTrajFiles.m`</li><li>`ScriptedEncounter.m`</li><li>`wpt2script.m`</li><li>`writeTrajectoryToFile.m`</li></ui> | Generated encounters can be output as both waypoints and Uncorrelated Encounter Model events. See the Example_Outputs [README](../Example_Outputs/README.md) for the format of these outputs.<br><br>`ScriptedEncounter.m` is a class that has all the necessary properties to define a scripted encounter – i.e., initial encounter geometry and Encounter Model events.<br><br>`wpt2script.m` is used to convert waypoints to Uncorrelated Encounter Model events. <br><br> `compute_delta_heading.m` computes turn rates from waypoints, and is a helper function for `wpt2script.m`.<br><br>`writeTrajectoryToFile.m` writes the generated ownship and intruder trajectories to a text file.<br><br>`readTrajFiles.m` can be used to read the trajectory file data into a results struct.|
+
+## 3rd Party Code
+
+Complete list of all third party code embedded in or accessed by the disclosed software when such software is run. This list must include, without limitation, all open source code, free executable code, public domain code, library code, and all other executable or source code not written by any of the authors, whether such code is directly embedded in the software or accessed by the software when it is executed.
+
+The MIT airspace encounter model team has not knowingly modified any of the third party code. While the licenses vary, we include the third party code in this repository directly or as git submodules for convenience. Any modifications to git submodules ([as these git commits are separate](https://git-scm.com/book/en/v2/Git-Tools-Submodules) from this repository) shall be in compliance with their respective license.
+
+| Code        |  Description | Software Source   | License Source  | [Git Submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)? | Modified? |
+| :-------------| :--  |:-------------| :-----| :--- | :--- |
+ini2struct.m | Parses .ini file into a structure | [File Exchange](https://www.mathworks.com/matlabcentral/fileexchange/45725-ini2struct) | [BSD-3 Clause](https://www.mathworks.com/matlabcentral/fileexchange/45725-ini2struct#license_modal) | No | No
+minmax.h | Min, Max macros | | GNU General Public License version 2 | No | No
+
+## Distribution Statement
+
+DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.
+
+© 2018, 2019, 2020 Massachusetts Institute of Technology.
+
+This material is based upon work supported by the National Aeronautics and Space Administration under Air Force Contract No. FA8702-15-D-0001. Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Aeronautics and Space Administration .
+
+Delivered to the U.S. Government with Unlimited Rights, as defined in DFARS Part 252.227-7013 or 7014 (Feb 2014). Notwithstanding any copyright notice, U.S. Government rights in this work are defined by DFARS 252.227-7013 or DFARS 252.227-7014 as detailed above. Use of this work other than as specifically authorized by the U.S. Government may violate any copyrights that exist in this work.

Encounter_Generation_Tool/ScriptedEncounter.m

@@ -0,0 +1,77 @@
+% Copyright 2018 - 2020, MIT Lincoln Laboratory
+% SPDX-License-Identifier: X11
+%%
+classdef ScriptedEncounter
+    %SCRIPTEDENCOUNTER An encounter between one or more aircraft
+    %   The initial geometry and subsequent controls of a scripted
+    %   encounter between two or more aircraft
+
+    properties
+        id
+        numberOfAircraft
+
+        % Initial quantities - Vectors of length this.numberOfAircraft
+
+        v_ftps @double     % Initial true airspeed
+        n_ft   @double     % Initial north coordinate
+        e_ft   @double     % Initial east coordinate
+        h_ft   @double     % Initial altitude AGL
+        heading_rad @double% Initial heading, clockwise of True North
+        pitch_rad   @double% Initial pitch angle
+        bank_rad     @double% Initial bank angle
+        a_ftpss     @double% Initial longitudinal acceleration
+
+        % Subsequent controls
+
+        updates @ EncounterModelEvents % Array of length this.numberOfAircraft of EncounterModelEvents objects
+
+        % Metadata
+        runTime_s @double; % Duration of encounter
+        altLayer @double; % Altitude layer are 500-1200, 1200-3000, 3000-5000, 5000-18000 for uncorrelated model
+
+    end
+
+    methods
+        function this = ScriptedEncounter( id, initial, varargin )
+            % Create a new ScriptedEncounter object
+            %
+            %   this = ScriptedEncounter()
+            %   this = ScriptedEncounter( id, initial, updates1, updates2 )
+
+            if( nargin > 0 )
+                this.id = id;
+                this.numberOfAircraft = numel( varargin );
+
+                for k = 1 : this.numberOfAircraft
+                    this.v_ftps(k) = initial.( [ 'v' num2str(k) '_ftps' ] );
+                    this.n_ft(k)   = initial.( [ 'n' num2str(k) '_ft' ] );
+                    this.e_ft(k)   = initial.( [ 'e' num2str(k) '_ft' ] );
+                    this.h_ft(k)   = initial.( [ 'h' num2str(k) '_ft' ] );
+                    this.heading_rad(k)   = initial.( [ 'psi' num2str(k) '_rad' ] );
+                    this.pitch_rad(k)   = initial.( [ 'theta' num2str(k) '_rad' ] );
+                    this.bank_rad(k)   = initial.( [ 'phi' num2str(k) '_rad' ] );
+                    this.a_ftpss(k)    = initial.( [ 'a' num2str(k) '_ftpss' ] );
+
+                    this.updates(k)  = EncounterModelEvents( 'event', varargin{k} );
+                end
+            end
+
+        end
+    end
+
+    % Useful derived quantities
+    properties(Dependent)
+        initialHorizontalSeparation_ft
+        initialVerticalSeparation_ft
+    end
+    methods
+        function v = get.initialHorizontalSeparation_ft( this )
+            v = sqrt( (this.n_ft(2:end) - this.n_ft(1)).^2 + (this.e_ft(2:end) - this.e_ft(1)).^2 );
+        end
+        function v = get.initialVerticalSeparation_ft( this )
+            v = abs( this.h_ft(2:end) - this.h_ft(1) );
+        end
+    end
+
+end
+