Document GeoDB; remove unused code; minor fixes

CHANGELOG.md

@@ -1,28 +1,47 @@
-# Version 0.5.0 (Jan 6, 2021)
+# Changelog
 
-- Allow plants to store input material for processing in later years
+All notable changes to this project will be documented in this file.
 
-# Version 0.4.0 (Sep 18, 2020)
+- The format is based on [Keep a Changelog][changelog].
+- This project adheres to [Semantic Versioning][semver].
+- For versions before 1.0, we follow the [Pkg.jl convention][pkjjl]
+  that `0.a.b` is compatible with `0.a.c`.
 
-- Generate simplified solution reports (CSV)
+[changelog]: https://keepachangelog.com/en/1.0.0/
+[semver]: https://semver.org/spec/v2.0.0.html
+[pkjjl]: https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0
+
+## [Unreleased]
+## Added
+- Allow user to specify locations as unique identifiers, instead of latitude and longitude (e.g. `us-state:IL` or `2018-us-county:17043`)
+
+## [0.5.0] -- 2021-01-06
+## Added
+- Allow plants to store input material for processing in later years
 
-# Version 0.3.3 (Aug 13, 2020)
+## [0.4.0] -- 2020-09-18
+## Added
+- Generate simplified solution reports (CSV)
 
+## [0.3.3] -- 2020-10-13
+## Added
 - Add option to write solution to JSON file in RELOG.solve
 - Improve error message when instance is infeasible
 - Make output file more readable
 
-# Version 0.3.2 (Aug 7, 2020)
+## [0.3.2] -- 2020-10-07
-
+## Added
 - Add "building period" parameter
 
-# Version 0.3.1 (July 17, 2020)
+## [0.3.1] -- 2020-07-17
-
+## Fixed
 - Fix expansion cost breakdown
 
-# Version 0.3.0 (June 25, 2020)
+## [0.3.0] -- 2020-06-25
-
+## Added
 - Track emissions and energy (transportation and plants)
+
+## Changed
 - Minor changes to input file format:
     - Make all dictionary keys lowercase
     - Rename "outputs (tonne)" to "outputs (tonne/tonne)"

Project.toml

@@ -1,7 +1,7 @@
 name = "RELOG"
 uuid = "a2afcdf7-cf04-4913-85f9-c0d81ddf2008"
 authors = ["Alinson S Xavier <axavier@anl.gov>"]
-version = "0.5.0"
+version = "0.5.1"
 
 [deps]
 CRC = "44b605c4-b955-5f2b-9b6d-d2bd01d3d205"

instances/s2.json

@@ -202,8 +202,7 @@
                     }
                 },
                 "L2": {
-                    "latitude (deg)": 0.5,
+                    "location": "2018-us-county:17043",
-                    "longitude (deg)": 0.5,
                     "capacities (tonne)": {
                         "0.0": {
                             "opening cost ($)": [

src/docs/format.md

@@ -182,6 +182,38 @@ The keys in the `capacities (tonne)` dictionary should be the amounts (in tonnes
 }
 ```
 
+### Geographic database
+
+Instead of specifying locations using latitudes and longitudes, it is also possible to specify them using unique identifiers, such as the name of a US state, or the county FIPS code. This works anywhere `latitude (deg)` and `longitude (deg)` are expected. For example, instead of:
+```json
+{
+    "initial amounts": {
+        "C1": {
+            "latitude (deg)": 37.27182,
+            "longitude (deg)": -119.2704,
+            "amount (tonne)": [934.56, 934.56]
+        },
+    }
+}
+```
+is is possible to write:
+```json
+{
+    "initial amounts": {
+        "C1": {
+            "location": "us-state:CA",
+            "amount (tonne)": [934.56, 934.56]
+        },
+    }
+}
+```
+Location names follow the format `db:id`, where `db` is the name of the database and `id` is the identifier for a specific location. RELOG currently includes the following databases:
+
+Database | Description | Examples
+---------|-------------|----------
+`us-state`| List of states of the United States. | `us-state:IL` (State of Illinois)
+`2018-us-county` | List of United States counties, as of 2018. IDs are 5-digit FIPS codes. | `2018-us-county:17043` (DuPage county in Illinois)
+
 ### Current limitations
 
 * Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation.
@@ -192,4 +224,3 @@ The keys in the `capacities (tonne)` dictionary should be the amounts (in tonnes
 ## Output Data Format (JSON)
 
 To be documented.
-

src/instance/geodb.jl

@@ -168,25 +168,6 @@ function _geodb_load_2018_us_county()::Dict{String,GeoRegion}
     )
 end
 
-# # 2018 US ZIP codes
-# # -----------------------------------------------------------------------------
-# function _extract_cols_2018_us_zcta(table::Shapefile.Table, i::Int)::OrderedDict{String,Any}
-#     return OrderedDict("id" => table.ZCTA5CE10[i])
-# end
-
-# function _geodb_load_2018_us_zcta()::Dict{String,GeoRegion}
-#     return _geodb_load_gov_census(
-#         db_name = "2018-us-zcta",
-#         extract_cols = _extract_cols_2018_us_zcta,
-#         shp_crc32 = 0x6391f5fc,
-#         shp_filename = "cb_2018_us_zcta510_500k.shp",
-#         shp_url = "https://www2.census.gov/geo/tiger/GENZ2018/shp/cb_2018_us_zcta510_500k.zip",
-#         population_url = "http://www2.census.gov/programs-surveys/popest/datasets/2010-2019/national/totals/nst-est2019-alldata.csv",
-#         population_crc32 = 0x191cc64c,
-#         population_col = "POPESTIMATE2019",
-#     )
-# end
-
 # US States
 # -----------------------------------------------------------------------------
 function _extract_cols_us_state(table::Shapefile.Table, i::Int)::OrderedDict{String,Any}
@@ -218,7 +199,6 @@ end
 
 function geodb_load(db_name::AbstractString)::Dict{String,GeoRegion}
     db_name == "2018-us-county" && return _geodb_load_2018_us_county()
-    db_name == "2018-us-zcta" && return _geodb_load_2018_us_zcta()
     db_name == "us-state" && return _geodb_load_us_state()
     error("Unknown database: $db_name")
 end

src/instance/parse.jl

@@ -100,6 +100,13 @@ function parse(json)::Instance
             disposal_limit = Dict(p => [0.0 for t = 1:T] for p in keys(output))
             disposal_cost = Dict(p => [0.0 for t = 1:T] for p in keys(output))
 
+            # GeoDB
+            if "location" in keys(location_dict)
+                region = geodb_query(location_dict["location"])
+                location_dict["latitude (deg)"] = region.centroid.lat
+                location_dict["longitude (deg)"] = region.centroid.lon
+            end
+
             # Disposal
             if "disposal" in keys(location_dict)
                 for (product_name, disposal_dict) in location_dict["disposal"]