Merge pull request #97 from dss-extensions/dss_capi-0.14.0

DSS C-API 0.14 and updated tests
dss-extensions · Feb 18, 2024 · fc8918d · fc8918d · PMeira · Feb 18, 2024
2 parents 34e3db2 + 3bea0cf
commit fc8918d
Show file tree

Hide file tree

Showing 17 changed files with 1,035 additions and 100 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -2,6 +2,14 @@
 
 For a more complete list of changes, visit the [Git repository and Releases page on GitHub](https://github.com/dss-extensions/OpenDSSDirect.jl).
 
+### OpenDSSDirect v0.9.6 Release Notes
+
+- Update the engine to DSS C-API v0.14.1. There are a few bugfixes but also an extensive list of new features, [please check the AltDSS/DSS C-API changelog](https://github.com/dss-extensions/dss_capi/blob/master/docs/changelog.md#version-0141-2024-02-16).
+- Export more modules; while previously accessible with `using OpenDSSDirect`, `import OpenDSSDirect` was missing many modules.
+- Enums `DSSJSONFlags` and `DSSCompatFlags` were updated.
+- Added enums `EnergyMeterRegisters`, `GeneratorRegisters`, `DSSPropertyNameStyle`, `DSSSaveFlags`.
+- Expose new API functions `Circuit.Save` (extended equivalent of `save circuit dir=...`, with several flags for customization), `Circuit.FromJSON`, `Circuit.ToJSON`. The JSON functions are still experimental.
+
 ### OpenDSSDirect v0.9.5 Release Notes
 
 - Update the DocStringExtensions dependency to avoid conflicts with other packages.
@@ -15,7 +23,7 @@ For a more complete list of changes, visit the [Git repository and Releases page
 - Update the engine to DSS C-API v0.13.3. This includes important bugfixes to UPFC, Capacitor, and Reactor components, as well as other small changes.
 - Update documentation.
 - Add new flag `DSSCompatFlags_SaveCalcVoltageBases`: this flag forces the `save circuit` to always include `CalcVoltageBases` in the saved files. 
-Use it with `Basic.DSSCompatFlags()`.
+Use it with `Basic.CompatFlags()`.
 
 ### OpenDSSDirect v0.9.2 Release Notes
 

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "OpenDSSDirect"
 uuid = "a8b11937-1041-50f2-9818-136bb7a8fb06"
 authors = ["Tom Short <[email protected]>"]
-version = "0.9.5"
+version = "0.9.6"
 
 [deps]
 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82"

diff --git a/deps/build.jl b/deps/build.jl
@@ -6,7 +6,7 @@ abstract type Windows <: AbstractOS end
 abstract type MacOS <: BSD end
 abstract type Linux <: BSD end
 
-const DSS_CAPI_TAG = "0.13.4"
+const DSS_CAPI_TAG = "0.14.1"
 
 function download(::Type{MacOS})
     if Sys.ARCH == :aarch64

diff --git a/docs/make.jl b/docs/make.jl
@@ -5,13 +5,14 @@ using Documenter, OpenDSSDirect
 
 makedocs(
     # options
-    modules = [
-               OpenDSSDirect,
-              ],
+    modules = [OpenDSSDirect, ],
     doctest = false,
     clean = false,
     checkdocs=:exports,
-    format = Documenter.HTML(size_threshold_ignore = ["api.md"]),
+    format = Documenter.HTML(
+        size_threshold_ignore = ["api.md"], 
+        sidebar_sitename = false
+    ),
     sitename = "OpenDSSDirect.jl",
     authors = "Tom Short",
     pages = Any[
@@ -26,8 +27,8 @@ makedocs(
         "License" => "LICENSE.md"]
 )
 
-# Deploy built documentation from Travis.
-# =======================================
+# Deploy built documentation from CI
+# ==================================
 
 deploydocs(
     # options

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -116,6 +116,25 @@ search: Circuit
   {truncated...}
 ```
 
+Besides that, the [`methods` function](https://docs.julialang.org/en/v1.10/base/base/#Base.methods)
+can be helpful to list the alternatives. Besides the getter (no value arguments) and setter 
+(when a value argument provided), most functions allow passing a `dss::DSSContext` argument. 
+For example:
+
+```julia
+julia> using OpenDSSDirect
+
+julia> methods(OpenDSSDirect.Loads.Name)
+# 4 methods for generic function "Name":
+[1] Name() in OpenDSSDirect.Loads at /home/user/.julia/packages/OpenDSSDirect/5wwHs/src/loads.jl:144
+[2] Name(dss::DSSContext) in OpenDSSDirect.Loads at /home/user/.julia/packages/OpenDSSDirect/5wwHs/src/loads.jl:141
+[3] Name(dss::DSSContext, Value::String) in OpenDSSDirect.Loads at /home/user/.julia/packages/OpenDSSDirect/5wwHs/src/loads.jl:147
+[4] Name(Value::String) in OpenDSSDirect.Loads at /home/user/.julia/packages/OpenDSSDirect/5wwHs/src/loads.jl:150
+```
+
+For typical usage with a single circuit, users can use the variations without this argument. 
+For using multiple DSS circuits and potentially multiple circuits, provide the context explicitly.
+
 Here is a list of modules supported by this API. Each module has several functions.
 
 Functions or modules that are not present in the official OpenDSS implementation 

diff --git a/docs/src/assets/logo-dark.svg b/docs/src/assets/logo-dark.svg
diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg
diff --git a/docs/src/flags.md b/docs/src/flags.md
@@ -20,7 +20,6 @@ Pages = ["flags.md"]
 ```@docs
 Lib.ActionCodes
 Lib.AutoAddTypes
-Lib.BatchOperation
 Lib.CapControlModes
 Lib.CktModels
 Lib.ControlModes

diff --git a/scripts/generate.jl b/scripts/generate.jl
@@ -1,35 +1,27 @@
-using Clang
+using Clang.Generators
 
-# LIBCLANG_HEADERS are those headers to be wrapped.
-const LIBOPENDSS_INCLUDE = [
-                           joinpath(@__DIR__, "../../dss_capi/include/v7/") |> normpath,
-                          ]
+error("This is broken for modern versions, but should be fixed when DSS C-API v1.0 is released.")
+
+const LIBOPENDSS_INCLUDE = joinpath(@__DIR__, "../../dss_capi/include/") |> normpath
 
 const LIBOPENDSS_HEADERS = String[]
 
-for folder in LIBOPENDSS_INCLUDE
-    for header in readdir(folder)
-        if endswith(header, ".h")
-            push!(LIBOPENDSS_HEADERS, joinpath(folder, header))
-        end
-    end
-end
+push!(LIBOPENDSS_HEADERS, joinpath(LIBOPENDSS_INCLUDE, "dss_capi.h"))
+push!(LIBOPENDSS_HEADERS, joinpath(LIBOPENDSS_INCLUDE, "dss_capi_ctx.h"))
+
+# for header in readdir(folder)
+#     if endswith(header, ".h")
+#         push!(LIBOPENDSS_HEADERS, joinpath(LIBOPENDSS_INCLUDE, header))
+#     end
+# end
+
+LIBOPENDSS_ARGS = get_default_args() 
 
 LIBOPENDSS_ARGS = String[]
 for path in LIBOPENDSS_INCLUDE
-    push!(LIBOPENDSS_ARGS, "-I")
-    push!(LIBOPENDSS_ARGS, path)
+    push!(LIBOPENDSS_ARGS, "-I$path")
 end
 
-
-wc = init(; headers = LIBOPENDSS_HEADERS,
-            output_file = joinpath(@__DIR__, "../src/lib.jl"),
-            common_file = joinpath(@__DIR__, "../src/common.jl"),
-            clang_includes = vcat(LIBOPENDSS_INCLUDE..., CLANG_INCLUDE),
-            clang_args = LIBOPENDSS_ARGS,
-            header_wrapped = (root, current)->root == current,
-            header_library = x->"LIBRARY",
-            clang_diagnostics = true,
-            )
-
-run(wc)
+options = load_options(joinpath(@__DIR__, "generator.toml"))
+ctx = create_context(LIBOPENDSS_HEADERS, LIBOPENDSS_ARGS, options)
+build!(ctx)
diff --git a/scripts/generator.toml b/scripts/generator.toml
@@ -0,0 +1,7 @@
+[general]
+library_name = "libdss_capi"
+output_file_path = "../src/lib.jl"
+module_name = "lib"
+jll_pkg_name = "OpenDSSDirect"
+export_symbol_prefixes = [""]
+use_julia_native_enum_type = true
diff --git a/src/OpenDSSDirect.jl b/src/OpenDSSDirect.jl
@@ -1,43 +1,55 @@
 
 module OpenDSSDirect
 
-export ActiveClass
-export Basic
-export Bus
-export CapControls
-export Capacitors
-export Circuit
-export CktElement
-export Element
-export Error
-export Executive
-export Fuses
-export Generators
-export Isource
-export LineCodes
-export Lines
-export Loads
-export LoadShape
-export Meters
-export Monitors
-export Parser
-export PDElements
-export Progress
-export Properties
-export PVsystems
-export Reclosers
-export RegControls
-export Relays
-export Sensors
-export Settings
-export Solution
-export SwtControls
-export Text
-export Topology
-export Transformers
-export Vsources
-export XYCurves
-export YMatrix
+export ActiveClass 
+export Basic 
+export Bus 
+export Capacitors 
+export CapControls 
+export Circuit 
+export CktElement 
+export CNData 
+export CtrlQueue 
+export Element 
+export Error 
+export Executive 
+export Fuses 
+export Generators 
+export GICSources 
+export Isource 
+export LineCodes 
+export LineGeometries 
+export Lines 
+export LineSpacings 
+export Loads 
+export LoadShape 
+export Meters 
+export Monitors 
+export Parallel 
+export Parser 
+export PDElements 
+export Progress 
+export Properties 
+export PVsystems 
+export Reactors 
+export Reclosers 
+export ReduceCkt 
+export RegControls 
+export Relays 
+export Sensors 
+export Settings 
+export Solution 
+export Storages 
+export SwtControls 
+export Text 
+export Topology 
+export TSData 
+export Transformers 
+export Vsources 
+export WireData 
+export XYCurves 
+export YMatrix 
+export ZIP
 export DSSContext
 
 export dss
@@ -151,6 +163,8 @@ function __init__()
 
     # Load the default descriptions/help strings
     Lib.DSS_SetPropertiesMO(abspath(joinpath(@__DIR__, "../deps/messages/properties-en-US.mo")))
+    # Leave the properties with the legacy names for now
+    Lib.Settings_SetPropertyNameStyle(C_NULL, 2)
 
     if !Sys.islinux()
         global commandhelp = Dict{String, String}()

diff --git a/src/circuit.jl b/src/circuit.jl
@@ -1,8 +1,15 @@
 module Circuit
 
+using DocStringExtensions
+
 using ..Lib
 using ..Utils
 
+@template (FUNCTIONS, METHODS) = """
+                                 $(TYPEDSIGNATURES)
+                                 $(DOCSTRING)
+                                 """
+
 """Compute capacity"""
 function Capacity(dss::DSSContext, Start, Increment)::Float64
     return @checked Lib.Circuit_Capacity(dss.ctx, Start, Increment)
@@ -286,4 +293,57 @@ function ElementLosses(dss::DSSContext, Idx::Vector{Int32})::Vector{ComplexF64}
 end
 ElementLosses(Idx::Vector{Int32}) = ElementLosses(DSS_DEFAULT_CTX, Idx)
 
+"""EXPERIMENTAL: Loads a full circuit from a JSON-encoded string. The data must 
+be encoded using the proposed AltDSS Schema, see
+https://github.com/dss-extensions/altdss-schema/ and 
+https://github.com/orgs/dss-extensions/discussions/ for links to docs and to
+provide feedback for future revisions.
+
+The options argument is an integer bitset from the enum `DSSJSONFlags`.
+
+(API Extension)"""
+function FromJSON(dss::DSSContext, circ::String, options::Int32)
+    @checked Lib.Circuit_FromJSON(dss.ctx, Cstring(pointer(circ)), options)
+end
+FromJSON(circ::String, options::Int32) = FromJSON(DSS_DEFAULT_CTX, circ, options)
+
+"""EXPERIMENTAL: Returns the general circuit data, including all DSS objects, as a
+JSON-encoded string. The data is encoded using the proposed AltDSS Schema, see
+https://github.com/dss-extensions/altdss-schema/ and 
+https://github.com/orgs/dss-extensions/discussions/ for links to docs and to
+provide feedback for future revisions.
+
+The options argument is an integer bitset from the enum `DSSJSONFlags`.
+
+(API Extension)"""
+function ToJSON(dss::DSSContext, options::Int32)::String
+    return get_string(@checked Lib.Circuit_ToJSON(dss.ctx, options))
+end
+ToJSON(options::Int32) = ToJSON(DSS_DEFAULT_CTX, options)
+
+"""
+Equivalent of the "save circuit" DSS command, but allows customization
+through the `saveFlags` argument, which is a set of bit flags. 
+See the `DSSSaveFlags` enumeration for available flags:
+
+- `CalcVoltageBases`: Include the command CalcVoltageBases.
+- `SetVoltageBases`: Include commands to set the voltage bases individually.
+- `IncludeOptions`: Include most of the options (from the Set/Get DSS commands).
+- `IncludeDisabled`: Include disabled circuit elements (and LoadShapes).
+- `ExcludeDefault`: Exclude default DSS items if they are not modified by the user.
+- `SingleFile`: Use a single file instead of a folder for output.
+- `KeepOrder`: Save the circuit elements in the order they were loaded in the active circuit. Guarantees better reproducibility, especially when the system is ill-conditioned. Requires "SingleFile" flag.
+- `ExcludeMeterZones`: Do not export meter zones (as "feeders") separately. Has no effect when using a single file.
+- `IsOpen`: Export commands to open terminals of elements.
+- `ToString`: to the result string. Requires "SingleFile" flag.
+
+If `SingleFile` is enabled, the path name argument (`dirOrFilePath`) is the file path,
+otherwise it is the folder path. For string output, the argument is not used.
+
+(API Extension)"""
+function Save(dss::DSSContext, dirOrFilePath::String, saveFlags::Int32)::String
+    return get_string(@checked Lib.Circuit_Save(dss.ctx, Cstring(pointer(dirOrFilePath)), saveFlags))
+end
+Save(dirOrFilePath::String, saveFlags::Int32) = Save(DSS_DEFAULT_CTX, dirOrFilePath, saveFlags)
+
 end