lazy artifacts, matpower, default types

Artifacts.toml

@@ -1,6 +1,15 @@
 [PGLib_opf]
 git-tree-sha1 = "0e8968a89b6ad43910a8eda4ec30656add35cf91"
+lazy = true
 
     [[PGLib_opf.download]]
     sha256 = "f1421ce22f0a7b9de8a8b2111776b496348220192ad24aace392c3bf608706c2"
     url = "https://github.com/power-grid-lib/pglib-opf/archive/refs/tags/v23.07.tar.gz"
+
+[MATPOWER_opf]
+lazy = true
+git-tree-sha1 = "f7681b06246af894949f30b607ac66ffe5fc3101"
+
+    [[MATPOWER_opf.download]]
+    sha256 = "5f08ced1a32e8d0d658ee54b73678c7364a899bae479882f2bc419e91442b69f"
+    url = "https://github.com/MATPOWER/matpower/archive/refs/tags/8.1.tar.gz"

Project.toml

@@ -1,11 +1,13 @@
 name = "ExaPowerIO"
 uuid = "14903efe-9500-4d7f-a589-7ab7e15da6de"
 authors = ["Archim Jhunjhunwala <[email protected]>"]
-version = "0.1.2"
+version = "0.2.0"
 
 [deps]
 Artifacts = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
+LazyArtifacts = "4af54fe1-eca0-43a8-85a7-787d91b784e3"
 
 [compat]
 Artifacts = "1.11.0"
+LazyArtifacts = "1.11.0"
 julia = "1.9"

benchmark/Project.toml

@@ -1,15 +1,13 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
-ExaPowerIO = "14903efe-9500-4d7f-a589-7ab7e15da6de"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 PGLib = "07a8691f-3d11-4330-951b-3c50f98338be"
 PProf = "e4faabce-9ead-11e9-39d9-4379958e3056"
 PowerModels = "c36e90e8-916a-50a6-bd94-075b64ef4655"
 
 [compat]
 BenchmarkTools = "~1.6"
-ExaPowerIO = "~0.1"
 JLD2 = "~0.5"
 PGLib = "~0.2"
 PProf = "~3.2"
-PowerModels = "~0.21"
+PowerModels = "~0.21"

benchmark/runbenchmarks.jl

@@ -1,4 +1,8 @@
-using ExaPowerIO, BenchmarkTools, PowerModels, PGLib, Profile, PProf, Logging, JLD2
+using BenchmarkTools, PowerModels, PGLib, Profile, PProf, Logging, JLD2, Pkg
+
+Pkg.activate("..")
+
+using ExaPowerIO
 
 PowerModels.silence()
 
@@ -27,7 +31,7 @@ datadir = "../data/"
 function run_exapower!()
     data = Vector{ExaPowerIO.PowerData}(undef, length(CASES))
     for (i, dataset) in enumerate(CASES)
-        data[i] = ExaPowerIO.parse_pglib(Float64, Vector, dataset; out_type=ExaPowerIO.PowerData)
+        data[i] = ExaPowerIO.parse_matpower(dataset; library=:pglib)
     end
     data
 end

docs/make.jl

@@ -2,7 +2,6 @@ using Pkg
 Pkg.activate(@__DIR__)
 Pkg.develop(path=dirname(@__DIR__))
 
-
 using Documenter, ExaPowerIO, Literate
 
 const _PAGES = [

docs/src/user.md

@@ -1,15 +1,64 @@
 # User Documentation
-ExaPowerIO exports three functions:
+ExaPowerIO exports 1 function:
 
 ```@docs
-ExaPowerIO.parse_pglib
-ExaPowerIO.parse_file
+ExaPowerIO.parse_matpower
 ```
 
 ```@docs
 ExaPowerIO.PowerData
 ExaPowerIO.BusData
 ExaPowerIO.GenData
 ExaPowerIO.BranchData
+ExaPowerIO.ArcData
 ExaPowerIO.StorageData
 ```
+
+### Example Usage
+
+```@meta
+# otherwise we get "Downloading artifact ..." in the output and doctests fail
+DocTestSetup = quote
+    using ExaPowerIO
+    result = parse_matpower("pglib_opf_case3_lmbd.m"; library=:pglib);
+end
+
+DocTestTeardown = quote
+    # restore settings, release resources, ...
+end
+```
+
+```jldoctest
+julia> using ExaPowerIO
+
+julia> result = parse_matpower("pglib_opf_case3_lmbd.m"; library=:pglib);
+
+julia> result.version
+"2"
+
+julia> result.baseMVA
+100.0
+
+julia> result.bus
+3-element Vector{BusData{Float64}}:
+ BusData{Float64}(1, 3, 1.1, 0.4, 0.0, 0.0, 1, 1.0, 0.0, 240.0, 1, 1.1, 0.9)
+ BusData{Float64}(2, 2, 1.1, 0.4, 0.0, 0.0, 1, 1.0, 0.0, 240.0, 1, 1.1, 0.9)
+ BusData{Float64}(3, 2, 0.95, 0.5, 0.0, 0.0, 1, 1.0, 0.0, 240.0, 1, 1.1, 0.9)
+
+julia> result.gen
+3-element Vector{GenData{Float64}}:
+ GenData{Float64}(1, 10.0, 0.0, 10.0, -10.0, 1.0, 100.0, 1, 20.0, 0.0, 1, true, 0.0, 0.0, 3, (1100.0, 500.0, 0.0))
+ GenData{Float64}(2, 10.0, 0.0, 10.0, -10.0, 1.0, 100.0, 1, 20.0, 0.0, 2, true, 0.0, 0.0, 3, (850.0000000000001, 120.0, 0.0))
+ GenData{Float64}(3, 0.0, 0.0, 10.0, -10.0, 1.0, 100.0, 1, 0.0, 0.0, 3, true, 0.0, 0.0, 3, (0.0, 0.0, 0.0))
+
+julia> result.branch
+3-element Vector{BranchData{Float64}}:
+ BranchData{Float64}(1, 3, 0.065, 0.62, 0.225, 0.225, 0.0, 0.0, 90.0, 90.0, 90.0, 1.0, 0.0, 1, -0.5235987755982988, 0.5235987755982988, 1, 4, -0.16725635252492763, 1.5953682856223865, -0.16725635252492763, 1.5953682856223865, 0.16725635252492763, -1.3703682856223864, 0.16725635252492763, -1.3703682856223864)
+ BranchData{Float64}(3, 2, 0.025, 0.75, 0.35, 0.35, 0.0, 0.0, 0.5, 0.5, 0.5, 1.0, 0.0, 1, -0.5235987755982988, 0.5235987755982988, 2, 5, -0.044395116537180916, 1.3318534961154274, -0.044395116537180916, 1.3318534961154274, 0.044395116537180916, -0.9818534961154274, 0.044395116537180916, -0.9818534961154274)
+ BranchData{Float64}(1, 2, 0.042, 0.9, 0.15, 0.15, 0.0, 0.0, 90.0, 90.0, 90.0, 1.0, 0.0, 1, -0.5235987755982988, 0.5235987755982988, 3, 6, -0.05173917542536994, 1.1086966162579273, -0.05173917542536994, 1.1086966162579273, 0.05173917542536994, -0.9586966162579272, 0.05173917542536994, -0.9586966162579272)
+
+julia> result.storage
+StorageData{Float64}[]
+
+
+```

src/ExaPowerIO.jl

@@ -1,72 +1,45 @@
 module ExaPowerIO
 
-using Artifacts
-
-const PGLib_opf = joinpath(artifact"PGLib_opf","pglib-opf-23.07")
+using Artifacts, LazyArtifacts
 
 include("parser.jl")
 
 """
-    function parse_pglib(
-        ::Type{T<:Real},
-        dataset_query :: String;
-        out_type=PowerData{T}
-    ) :: Union{PowerData{T}, NamedTuple} where T
-
-Searches the [PGLib database](https://github.com/power-grid-lib/pglib-opf) for ```dataset_query```, and errors if there is not exactly 1 result.
-Otherwise, the matching file is downloaded and parsed to return a value of type out_type.
-
-Each value will be parsed as a ```T```.
-
-Currently, out_type can only be ```ExaPowerIO.PowerData{T}```, or ```NamedTuple```.
-
-```julia
-parse_file(dataset_query; out_file) will return parse_file(Float64, dataset_query; out_file)
-```
+    function parse_matpower(
+        ::Type{T},
+        ::Type{V},
+        path :: String;
+        library=nothing,
+    ) :: PowerData{T} where {T<:Real, V<:AbstractVector}
+
+T and V can be ommited and have default values `Float64`, and `Vector` respectively.
+
+`library` can be one of the following values:
+- `:nothing` indicates that the filesystem should be searched for `path`
+- `:pglib` indicates that the [PGLib database](https://github.com/power-grid-lib/pglib-opf) should be searched for `path`
+- `:matpower` indicates that the [MATPOWER database](https://github.com/MATPOWER/matpower) should be searched for `path`
 """
-function parse_pglib(
+function parse_matpower(
     ::Type{T},
     ::Type{V},
-    dataset_query :: String;
-    out_type=PowerData
+    path :: String;
+    library=nothing,
 ) :: Union{NamedTuple, PowerData{T}} where {T<:Real, V<:AbstractVector}
-    pglib_file = joinpath(PGLib_opf, dataset_query)
-    if !isfile(pglib_file)
-        throw(error("No matches found for pglib dataset: $dataset_query"))
+    if library == :pglib
+        PGLib_opf = joinpath(artifact"PGLib_opf", "pglib-opf-23.07")
+        path = joinpath(PGLib_opf, path)
+    elseif library == :matpower
+        MATPOWER_opf = joinpath(artifact"MATPOWER_opf", "data")
+        path = joinpath(MATPOWER_opf, path)
     end
-    parse_file(T, V, pglib_file; out_type)
+    isfile(path) || throw(error("Invalid file $path for library $library"))
+    return parse_matpower_inner(T, V, path)
 end
 
-convert(::Type{T}, data::PowerData) where T<:PowerData = data
-convert(::Type{T}, data::PowerData) where T<:NamedTuple = struct_to_nt(data)
-
-"""
-    parse_file(
-        fname :: String;
-        out_type=PowerData{T}
-    )
-
-Parses the Matpower file specified by fname, and returns a value of type out_type.
-
-Each value will be parsed as a ```T```.
-
-Currently, out_type can only be ```ExaPowerIO.PowerData{T}```, or ```NamedTuple```.
-
-```julia
-parse_file(dataset_query; out_file) will return parse_file{Float64}(dataset_query; out_file)
-```
-"""
-function parse_file(
-    ::Type{T},
-    ::Type{V},
-    fname :: String;
-    out_type=PowerData
-) :: Union{NamedTuple, PowerData{T}} where {T<:Real, V<:AbstractVector}
-    @info "Loading MATPOWER file at " * fname
-    data = parse_matpower(T, V, fname)
-    return convert(out_type, data)
-end
+parse_matpower(path; library=nothing) = parse_matpower(Float64, Vector, path; library)
+parse_matpower(::Type{T}, path; library=nothing) where {T<:Real} = parse_matpower(T, Vector, path; library)
+parse_matpower(::Type{V}, path; library=nothing) where {V<:Vector} = parse_matpower(Float64, V, path; library)
 
-export parse_file, parse_pglib, PowerData, BusData, GenData, BranchData, StorageData
+export parse_matpower, PowerData, BusData, GenData, BranchData, ArcData, StorageData
 
 end # module ExaPowerIO