Version 2.0 with OOP

See CHANGELOG.md

.gitignore

@@ -40,3 +40,4 @@ octave-workspace
 *.dat
 *.zip
 *.TMP
+*.fig

CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [2.0.0] - 2021-10-01
+
+### Added
+
+- New default RUN script of `RUN_2_geospatial_uncor`
+- `CreateTradespacePairingGeo` is a helper function crete a tradespace of different combinations of input variables to `createEncounters_2`
+- `trackTimetable2NEU` converts tracks in timetable format to an array corresponding to time, north, east, and up coordinates
+- `adjustTrack` will adjust tracks based on output of `samplespeedalt`
+- `estimateSpeedFromGeodetic` is a helper function to estimate speed based on latitude and longitude
+- `preallocAnchors`, `createISO31662Grid`, and `parseGeoTrajDirectory` helper functions for step one
+- Persistent system environment variable of `AEM_DIR_GEOPAIR` established
+
+### Changed
+
+- Inputs to `findPairs_1` changed to take advantage of calling `preallocAnchors` within `findPairs_1`. The step one RUN script was updated accordingly.
+- `createEncounters_2` no longer reads in pre-generated files of tracks generated from the Bayesian encounter models; instead encounter model based tracks are generated dynamically using the new `UncorEncounterModel` class added to `em-model-manned-bayes`
+- `createEncounters_2` will try multiple times to create an encounter with aircraft 1 and will now resample an encounter model to generate new Bayes tracks if needed. The previous version gave up too easily.
+- `createEncounters_2` no longer organized loops by clusters and all clustering has been removed
+- `createEncounters_2` loads FAA digital obstacle file using `gridDOF` from `em-core`
+- `createEncounters_2` stores tracks as a `timetable`, a type of table that associates a time with each row. Helper functions like `findconflict`, `samplespeedalt`, and `findCropIdx` have been updated accordingly
+- `createEncounters_2` outputs a table containing encounter metadata
+- `createEncounters_2` and `loadTrack` will enforce the altitude range (altRange1_ft_agl, altRange2_ft_agl) when sampling the Bayes tracks. For Bayes tracks, altitude still cannot resampled using `samplespeedalt` and `adjustTrack`.
+- `findconflict` now considers HMD, VMD, and time criteria. It previously only assessed HMD.
+- `findCropIdx` also now checks for initial horizontal and vertical separation criteria
+- Renamed `neu_to_wp_struct` to to `neu2Waypoints`
+- Renamed `startup` to `startup_pairing_geo`
+- DEM handling updated based on improvements to `msl2agl` from `em-core`
+- Better random seed control
+- Improved plotting
+- Improved organization through the use of the code directory
+
+### Fixed
+
+- `samplespeedalt` handles rare case where the altitude span is less than 25 resulting in `adjustSpan_ft_agl` being empty
+- Fixed bug in `findConflict` when calculating `hmd_ft` and `vmd_ft` but tracks are not near each other
+- Various functions renamed using camelCase
+
+### Removed
+
+- `croptracks`, `calcLegsTime`, `neu2wpstruct`, `updatewaypointstruct` removed due to the addition of `trackTimetable2NEU` and updates to `findconflict` and `findCropIdx`
+- `interpTime` removed because time based interpolation is handled using the built-in functionality of the `timetable` type
+- `RUN_2_sUAS_uncor` and `RUN_2_sUAS_unconv` removed because they were deprecated by the more generalized `RUN_2_geospatial_uncor` script
+- `RUN_2_sUAS_HAA` removed due to change of sampling Bayesian networks at runtime. The Bayesian helicopter air ambulance model hasn't been tested yet with the `EncounterModel` objects in em-model-manned-bayes. This functionality maybe reintroduced in a future release.
+
+## [1.1.0] - 2020-08-10
+
+### Added
+
+- SPDX headers
+
+### Changed
+
+- Improving handling of Bayes tracks from em-model-manned-bayes
+
+### Fixed
+
+- Addressed bug `placeTrack` where tracks were not correctly rotated
+
+## [1.0.0] - 2020-06-24
+
+### Added
+
+- Initial public release

LICENSE

@@ -1,6 +1,6 @@
 BSD 2-Clause License
 
-Copyright (c) 2019,2020 Massachusetts Institute of Technology
+Copyright (c) 2019-2021 Massachusetts Institute of Technology
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -9,14 +9,16 @@ This repository is a collection of MATLAB code to generate uncorrelated encounte
     - [Contribution](#contribution)
   - [Method](#method)
   - [Run Order](#run-order)
-    - [Confirm Persistent System Environment Variable](#confirm-persistent-system-environment-variable)
+    - [Persistent System Environment Variable](#persistent-system-environment-variable)
+    - [Confirm Other Persistent System Environment Variable](#confirm-other-persistent-system-environment-variable)
     - [em-core](#em-core)
-    - [Generate trajectories](#generate-trajectories)
-    - [Identify Pairs (RUN_1*)](#identify-pairs-run1)
-      - [Parameters: findPairs_1](#parameters-findpairs1)
+    - [Generate geospatial trajectories](#generate-geospatial-trajectories)
+    - [Identify Pairs (RUN_1*)](#identify-pairs-run_1)
+      - [Parameters: findPairs_1](#parameters-findpairs_1)
+      - [Performance](#performance)
       - [Plotting](#plotting)
-    - [Generate Encounters (RUN_2*)](#generate-encounters-run2)
-      - [Parameters: createEncounters_2](#parameters-createencounters2)
+    - [Generate Encounters (RUN_2*)](#generate-encounters-run_2)
+      - [Parameters: createEncounters_2](#parameters-createencounters_2)
   - [Example Encounters](#example-encounters)
     - [Encounter Dynamics](#encounter-dynamics)
       - [Crossing, US-TN](#crossing-us-tn)
@@ -77,27 +79,41 @@ Then for each grid coordinate and pairs of tracks (multi-threat encounters are n
 
 Code developed and tested in Windows for Matlab R2018a and R2019b. The dev machine had a CPU of Intel Xeon Gold 6130 at 2.10GHz and 64 GB of RAM. The built-in Matlab function [`parfor`](https://www.mathworks.com/help/matlab/ref/parfor.html) is used routinely throughout the code. Majority of the computation intensive work is related to working with digital elevation models or loading files.
 
-### Confirm Persistent System Environment Variable
+### Persistent System Environment Variable
+
+Immediately after cloning this repository, [create a persistent system environment](https://superuser.com/q/284342/44051) variable titled `AEM_DIR_GEOPAIR` with a value of the full path to this repository root directory.
+
+In unix there are many ways to do this, here is an example using [`/etc/profile.d`](https://unix.stackexchange.com/a/117473). Create a new file `aem-env.sh` using `sudo vi /etc/profile.d/aem-env.sh` and add the command to set the variable:
+
+```bash
+export AEM_DIR_GEOPAIR=PATH TO /em-pairing-geospatial
+```
+
+You can confirm `AEM_DIR_BAYES` was set in unix by inspecting the output of `env`.
+
+### Confirm Other Persistent System Environment Variable
 
 Persistent system variables are used to reference different repositories within the Airspace Encounter Models organization. Confirm that they have been set.
 
 | Variable Name  | Referring Repository |
 | :------------- | :------------- |
 `AEM_DIR_BAYES` | [`em-model-manned-bayes`](https://github.com/Airspace-Encounter-Models/em-model-manned-bayes)
 `AEM_DIR_CORE` | [`em-core`](https://github.com/Airspace-Encounter-Models/em-core)
-`AEM_DIR_GEOSPATIAL` | `em-model-geospatial`
+`AEM_DIR_GEOSPATIAL` | [`em-model-geospatial`](https://github.com/Airspace-Encounter-Models/em-model-geospatial)
 
 ### em-core
 
 If you have not already, complete the initial setup associated with the [`em-core`](https://github.com/Airspace-Encounter-Models/em-core) repository.
 
-### Generate trajectories
+### Generate geospatial trajectories
 
-Using a model specific repository, such as [`em-model-manned-bayes`](https://github.com/Airspace-Encounter-Models/em-model-manned-bayes) or `em-model-geospatial`, generate uncorrelated independent trajectories.
+Using a model specific repository, such as `em-model-geospatial`, generate uncorrelated independent trajectories.
 
 ### Identify Pairs (RUN_1*)
 
-The [`RUN_1.m`](RUN_1.m) script calls [`findPairs_1`](findPairs_1.m) and determines which trajectories generated by `em-model-geospatial` are within the distance defined by `anchorRange_nm` of the coordinates specified by `gridLat_deg` and `gridLon_deg`. These coordinates are referred to as the "anchor point." As noted in the [Output Directory](#output-directory) section, the output of [`RUN_1.m`](RUN_1.m) uses the "pairs" prefix.
+The [`RUN_1.m`](RUN_1.m) script calls [`findPairs_1`](findPairs_1.m) and determines which trajectories generated by `em-model-geospatial` are within the distance defined by `anchorRange_nm` of the coordinates specified by `gridLat_deg` and `gridLon_deg`.
+
+ These coordinates are referred to as the "anchor point." As noted in the [Output Directory](#output-directory) section, the output of [`RUN_1.m`](RUN_1.m) uses the "pairs" prefix.
 
 The high-level workflow for identifying feasible pairs and anchor points is:
 
@@ -107,20 +123,36 @@ The high-level workflow for identifying feasible pairs and anchor points is:
 
 #### Parameters: findPairs_1
 
-The script is based on the [`findPairs_1`](findPairs_1.m) function, which has the following parameters:
+The script is based on the [`findPairs_1`](findPairs_1.m) function. A notable helper functions is `preallocAnchors` and [`findPairs_1`](findPairs_1.m) has the following parameters:
 
 | Parameter  | Example |  Description |
 | :------------- | :-- | :------------- |
+| iso_3166_2 | `US-MA` | [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivision code for administrative boundary
 | inDir | `dir([getenv('AEM_DIR_GEOSPATIAL') filesep 'output' filesep 'trajectories' filesep 'US-MA' '*' filesep '*'])` | Cell array of directories from output of `em-model-geospatial/RUN_OSM_2_**.m`
 | outHash | `all_US-MA` | Text to append to output filename
-| gridLat_deg | N X 1 double column array | List of latitude coordinates in decimal degrees
-| gridLon_deg | N X 1 double column array | List of longitude coordinates in decimal degrees
-| anchorRange_nm | `1.25` | Maximum allowable distance.=, in nautical miles, aircraft can be away from a anchor point
-| airspace | `[getenv('AEM_DIR_CORE') filesep 'output' filesep 'airspace-B-C-D-24-Oct-2019.mat']` | Output from `em-core/matlab/**/RUN_Airspace_1.m` |
+| anchorRange_nm | `1.00` | Maximum allowable distance, in nautical miles, aircraft can be away from a anchor point
 | classInclude | `{'B','C','D','O'}` | Airspace classes to include
+| fileAirspace | `[getenv('AEM_DIR_CORE') filesep 'output' filesep 'airspace.mat']` | Filename of the output from `em-core/matlab/**/RUN_Airspace_1.m` |
 | spheroid | [`wgs84Ellipsoid('nm')`](https://www.mathworks.com/help/map/ref/wgs84ellipsoid.html) | [Reference ellipsoid](https://www.mathworks.com/help/map/reference-spheroids.html)
+| seed | `1` | If not empty, the random seed to use
 | isSave | `true` | If true, save to file
 
+#### Performance
+
+The following table are reference performance benchmarks when `anchorRange_nm = 1.00`.
+
+| ISO 3166-2  | # Anchor Points | # Geospatial Files | # Clusters | LLSC Run Time (s) |  Windows Local Run Time (s) |
+| :------------- | --: | --: | --: | --: | --: |
+| US-CO | 101,170 | 8,098 | 17 | 188 | 160
+| US-HI | 5,254 | 195 | 10 | 90 | 67
+| US-KS | 79,587 | 15,724 | 14 | 272 | 206
+| US-MA | 8,305 | 4,344 | 4 | 136 | 76
+| US-MS | 42,957 |4,738 | 11 | 171 | 137
+| US-NC | 45,716 | 12,247 | 15 | 208 | 150
+| US-ND | 78,447 | 3,487 | 14 | 183 | 152
+| US-NV | 108,163 | 2,514 | 26 | 147 | 107
+| US-NY | 54,465 | 11,700| 22 | 219 | 146
+
 #### Plotting
 
 The output of [`RUN_1.m`](RUN_1.m) can be visualized using [`PLOT_1.m`](PLOT_1.m). This script uses MATALB's [`geobasemap`](https://www.mathworks.com/help/matlab/creating_plots/access-basemaps-in-matlab.html) capabilities to color pairs of `gridLat_deg` and `gridLon_deg` coordinates by the number of geospatial trajectories within the `anchorRange_nm` distance. The [Discussion](#discussion) section includes example outputs of [`PLOT_1.m`](PLOT_1.m).
@@ -137,28 +169,32 @@ These scripts are based on the [`createEncounters_2`](createEncounters_2.m) func
 
 | Parameter  | Example | Description |
 | :------------- | :--- | :------------- |
-| inFile | `['output' filesep pairs-all_US-MA-anchorRange1.25.mat]` | Output from RUN_1
+| inAnchors | `['output' filesep pairs-all_US-MA-anchorRange1.25.mat]` | Either a .mat containing a the table output from RUN_1 or the table itself
+| outDir | `[getenv('AEM_DIR_GEOPAIR') filesep 'output' filesep '2_encounters']` | Directory where encounters are saved
 | encTime_s | `60` | Encounter duration in seconds
 | thresHorz_ft  | `500` |Conflict range threshold in feet
 | thresVert_ft  | `100` |Conflict vertical separation threshold in feet
 | initHorz_ft | `[6076 15190]` | Initial horizontal range in feet
 | initVert_ft | `[0 500]` | Initial vertical separation magnitude in feet
-| maxEncPerPair | `10` | Maximum encounters to generate for each combination of anchor coordinates and aircraft tracks
-| timeStep_s | `1` |Update rate in seconds
+| maxEncPerPair | `1` | Maximum encounters to generate for each combination of anchor coordinates and aircraft tracks
+| timeStep| `1` | Update rate
 | isSampleAlt1 | `true` | If true, sample aircraft 1 AGL altitude from [`minAlt1_ft_agl` `maxAlt1_ft_agl`]
 | minAlt1_ft_agl | `100` | Minimum sampled AGL altitude for aircraft 1
 | maxAlt1_ft_agl | `400` | Maximum sampled AGL altitude for aircraft 1
-| vrange1_kts | `[5 87]` | Minimum and maximum airspeed in knots of aircraft 1 (only if aircraft 1 isn't from a Bayes model)
-| acmodel2 | `bayes` | Denote if aircraft 2 was generated either from the geospatial or bayes model
-| demBayes | `dted1` | Digital elevation model to use when translating Bayes tracks from local (x,y,z) to (latitude, longitude, MSL altitude)
+| rangeV1_ft_s | `[9 168]` | Minimum and maximum airspeed in feet per second of aircraft 1 (only if aircraft 1 isn't from a Bayes model)
+| rangeV2_ft_s | `[9 168]` | Minimum and maximum airspeed in feet per second of aircraft 2 (only if aircraft 2 isn't from a Bayes model)
+| acmodel1 | `mdlType1` | Denote if aircraft 1 should be pre-generated trajectory from `em-model-geospatial` or sampled from `em-model-manned-bayes`
+| bayesFile1 | `[getenv('AEM_DIR_BAYES') filesep 'model' filesep 'uncor_1200only_fwse_v1p2.txt']` | Which Bayesian encounter model ASCII parameter file to use if `mdlType1 = 'bayes'`
+| dem | `dted1` | Digital elevation model to use when translating Bayes tracks from local (x,y,z) to (latitude, longitude, MSL altitude)
+| demBackup | `globe` | Digital elevation model to use when translating Bayes tracks from local (x,y,z) to (latitude, longitude, MSL altitude)
 | z_agl_tol_ft| `250` | Altitude tolerance when translating to MSL altitude from a Bayes track sampled in AGL
 | dofFile| `[getenv('AEM_DIR_CORE') filesep 'output' filesep 'dof-' '25-Feb-2020' '.mat']` | Output from `em-core/matlab/**/RUN_readfaadof.m`
 | dofObs| `{'silo','tower','windmill'}` | Cell array of obstacles to include
 | dofMinHeight_ft | `100` | Minimum height in feet of obstacles to include
 | dofMaxRange_ft | `500` | Horizontal separation in feet between Bayes aircraft and center of obstacles
 | dofMaxVert_ft | `50` | Vertical separation in feet between Bayes aircraft and the top of obstacles
 | classInclude | `{'B','C','D','O'}` | Airspace classes to include
-| spheroid | [`wgs84Ellipsoid('nm')`](https://www.mathworks.com/help/map/ref/wgs84ellipsoid.html) | [Reference ellipsoid](https://www.mathworks.com/help/map/reference-spheroids.html)
+| spheroid | [`wgs84Ellipsoid('ft')`](https://www.mathworks.com/help/map/ref/wgs84ellipsoid.html) | [Reference ellipsoid](https://www.mathworks.com/help/map/reference-spheroids.html)
 | isPlot | `true` | If true, plot trajectories and anchor points
 | isZip | `true` | If true, will archive directory containing encounters into a single .zip file
 
@@ -316,10 +352,6 @@ Default output directory for RUN scripts and functions. Files and subdirectories
 
 ## Citation
 
-Please use this DOI number reference when citing the software:
-
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3978267.svg)](https://doi.org/10.5281/zenodo.3978267)
-
 Please use this publication when citing the high level concepts of the encounter generation method:
 
 <details> <summary> A. Weinert, M. Edwards, L. Alvarez, and S. Katz, “Representative Small UAS Trajectories for Encounter Modeling,” in AIAA Scitech 2020 Forum, 2020, pp. 1–10.</summary>
@@ -345,7 +377,7 @@ DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited
 
 This material is based upon work supported by the Federal Aviation 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 Federal Aviation Administration.
 
-© 2019, 2020 Massachusetts Institute of Technology.
+© 2019-2021 Massachusetts Institute of Technology.
 
 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.