From 059e465f2853faacca781d3fef0688b1ded6b10f Mon Sep 17 00:00:00 2001 From: Paulo Meira <10246101+PMeira@users.noreply.github.com> Date: Sat, 17 Feb 2024 18:21:13 -0300 Subject: [PATCH 1/5] Export more modules --- src/OpenDSSDirect.jl | 86 +++++++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 37 deletions(-) diff --git a/src/OpenDSSDirect.jl b/src/OpenDSSDirect.jl index 1c922620..deccec6e 100644 --- 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 From 16f0ab8bb743ec5e404244f65704e2d795aecea5 Mon Sep 17 00:00:00 2001 From: Paulo Meira <10246101+PMeira@users.noreply.github.com> Date: Wed, 8 Nov 2023 09:24:00 -0300 Subject: [PATCH 2/5] DSS C-API 0.14.1, new functions and updated tests --- NEWS.md | 10 ++- Project.toml | 2 +- deps/build.jl | 2 +- docs/src/flags.md | 1 - scripts/generate.jl | 44 +++++------ scripts/generator.toml | 7 ++ src/OpenDSSDirect.jl | 2 + src/circuit.jl | 53 +++++++++++++ src/common.jl | 110 +++++++++++++++++++++----- src/extensions.jl | 10 +-- src/lib.jl | 18 ++++- test/circuit.jl | 174 +++++++++++++++++++++++++++++++++++++++++ test/lines.jl | 5 ++ 13 files changed, 381 insertions(+), 57 deletions(-) create mode 100644 scripts/generator.toml diff --git a/NEWS.md b/NEWS.md index 0e3aad7b..7899885a 100644 --- 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 index 8aa6c7c2..499bd260 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "OpenDSSDirect" uuid = "a8b11937-1041-50f2-9818-136bb7a8fb06" authors = ["Tom Short "] -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 index 9bf5f31d..9f59b3d5 100644 --- 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/src/flags.md b/docs/src/flags.md index 0435a566..3a1854cd 100644 --- 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 index 98bda05c..4d72ff27 100644 --- 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 new file mode 100644 index 00000000..eae7a64e --- /dev/null +++ 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 index deccec6e..42231f21 100644 --- a/src/OpenDSSDirect.jl +++ b/src/OpenDSSDirect.jl @@ -163,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 index c4309fa5..3b97ca52 100644 --- a/src/circuit.jl +++ b/src/circuit.jl @@ -286,4 +286,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 diff --git a/src/common.jl b/src/common.jl index 588a27ce..f9d160f3 100644 --- a/src/common.jl +++ b/src/common.jl @@ -1,4 +1,4 @@ -# Automatically generated using Clang.jl +# Previously generated using Clang.jl; now updated manually @cenum MonitorModes::UInt32 begin MonitorModes_VI = 0 @@ -128,33 +128,18 @@ end StorageStates_Discharging = 1 end -@cenum DSSMessageType::Int32 begin - DSSMessageType_Error = -1 - DSSMessageType_General = 0 - DSSMessageType_Info = 1 - DSSMessageType_Help = 2 - DSSMessageType_Progress = 3 - DSSMessageType_ProgressCaption = 4 - DSSMessageType_ProgressFormCaption = 5 - DSSMessageType_ProgressPercent = 6 - DSSMessageType_FireOffEditor = 7 -end - -@cenum DSSJSONFlags::UInt32 begin +@enum DSSJSONFlags::Int32 begin DSSJSONFlags_Full = 1 DSSJSONFlags_SkipRedundant = 2 DSSJSONFlags_EnumAsInt = 4 DSSJSONFlags_FullNames = 8 DSSJSONFlags_Pretty = 16 DSSJSONFlags_ExcludeDisabled = 32 - DSSJSONFlags_SkipDSSClass = 64 + DSSJSONFlags_IncludeDSSClass = 64 DSSJSONFlags_LowercaseKeys = 128 -end - -@cenum BatchOperation::UInt32 begin - BatchOperation_Set = 0 - BatchOperation_Multiply = 1 - BatchOperation_Increment = 2 + DSSJSONFlags_IncludeDefaultObjs = 256 + DSSJSONFlags_SkipTimestamp = 512 + DSSJSONFlags_SkipBuses = 1024 end @cenum SolverOptions::UInt32 begin @@ -170,4 +155,87 @@ end DSSCompatFlags_BadPrecision = 2 DSSCompatFlags_InvControl9611 = 4 DSSCompatFlags_SaveCalcVoltageBases = 8 + DSSCompatFlags_ActiveLine = 16 + DSSCompatFlags_NoPropertyTracking = 32 + DSSCompatFlags_SkipSideEffects = 64 +end + +@cenum EnergyMeterRegisters::Int32 begin + EnergyMeterRegisters_kWh = 0 + EnergyMeterRegisters_kvarh = 1 + EnergyMeterRegisters_MaxkW = 2 + EnergyMeterRegisters_MaxkVA = 3 + EnergyMeterRegisters_ZonekWh = 4 + EnergyMeterRegisters_Zonekvarh = 5 + EnergyMeterRegisters_ZoneMaxkW = 6 + EnergyMeterRegisters_ZoneMaxkVA = 7 + EnergyMeterRegisters_OverloadkWhNorm = 8 + EnergyMeterRegisters_OverloadkWhEmerg = 9 + EnergyMeterRegisters_LoadEEN = 10 + EnergyMeterRegisters_LoadUE = 11 + EnergyMeterRegisters_ZoneLosseskWh = 12 + EnergyMeterRegisters_ZoneLosseskvarh = 13 + EnergyMeterRegisters_LossesMaxkW = 14 + EnergyMeterRegisters_LossesMaxkvar = 15 + EnergyMeterRegisters_LoadLosseskWh = 16 + EnergyMeterRegisters_LoadLosseskvarh = 17 + EnergyMeterRegisters_NoLoadLosseskWh = 18 + EnergyMeterRegisters_NoLoadLosseskvarh = 19 + EnergyMeterRegisters_MaxLoadLosses = 20 + EnergyMeterRegisters_MaxNoLoadLosses = 21 + EnergyMeterRegisters_LineLosseskWh = 22 + EnergyMeterRegisters_TransformerLosseskWh = 23 + EnergyMeterRegisters_LineModeLineLoss = 24 + EnergyMeterRegisters_ZeroModeLineLoss = 25 + EnergyMeterRegisters_ThreePhaseLineLoss = 26 + EnergyMeterRegisters_OnePhaseLineLoss = 27 + EnergyMeterRegisters_GenkWh = 28 + EnergyMeterRegisters_Genkvarh = 29 + EnergyMeterRegisters_GenMaxkW = 30 + EnergyMeterRegisters_GenMaxkVA = 31 + EnergyMeterRegisters_VBaseStart = 32 +end + +@cenum GeneratorRegisters::Int32 begin + GeneratorRegisters_kWh = 0 + GeneratorRegisters_kvarh = 1 + GeneratorRegisters_MaxkW = 2 + GeneratorRegisters_MaxkVA = 3 + GeneratorRegisters_Hours = 4 + GeneratorRegisters_Price = 5 +end + +@cenum DSSMessageType::Int32 begin + DSSMessageType_Error = -1 + DSSMessageType_General = 0 + DSSMessageType_Info = 1 + DSSMessageType_Help = 2 + DSSMessageType_Progress = 3 + DSSMessageType_ProgressCaption = 4 + DSSMessageType_ProgressFormCaption = 5 + DSSMessageType_ProgressPercent = 6 + DSSMessageType_FireOffEditor = 7 + DSSMessageType_ProgressSummary = 8 + DSSMessageType_ReportOutput = 9 + DSSMessageType_ShowOutput = 10 + DSSMessageType_ShowTreeView = 11 +end + +@cenum DSSPropertyNameStyle::Int32 begin + DSSPropertyNameStyle_Modern = 0 + DSSPropertyNameStyle_Lowercase = 1 + DSSPropertyNameStyle_Legacy = 2 +end + +@cenum DSSSaveFlags::Int32 begin + DSSSaveFlags_CalcVoltageBases = 1 + DSSSaveFlags_SetVoltageBases = 2 + DSSSaveFlags_IncludeOptions = 4 + DSSSaveFlags_IncludeDisabled = 8 + DSSSaveFlags_ExcludeDefault = 16 + DSSSaveFlags_SingleFile = 32 + DSSSaveFlags_KeepOrder = 64 + DSSSaveFlags_ExcludeMeterZones = 128 + DSSSaveFlags_IsOpen = 256 + DSSSaveFlags_ToString = 512 end diff --git a/src/extensions.jl b/src/extensions.jl index 3ba7d7b0..d6e4275a 100644 --- a/src/extensions.jl +++ b/src/extensions.jl @@ -12,9 +12,9 @@ Base.convert(::Type{LoadStatus}, x::Integer) = LoadStatus(x) Base.convert(::Type{LoadModels}, x::Integer) = LoadModels(x) Base.convert(::Type{LineUnits}, x::Integer) = LineUnits(x) Base.convert(::Type{GeneratorStatus}, x::GeneratorStatus) = GeneratorStatus(x) -Base.convert(::Type{BatchOperation}, x::BatchOperation) = BatchOperation(x) Base.convert(::Type{StorageStates}, x::StorageStates) = StorageStates(x) Base.convert(::Type{DSSMessageType}, x::DSSMessageType) = DSSMessageType(x) +Base.convert(::Type{DSSSaveFlags}, x::DSSSaveFlags) = DSSSaveFlags(x) # TODO: see https://github.com/dss-extensions/OpenDSSDirect.jl/issues/76 # Base.convert(::Type{SolverOptions}, x::SolverOptions) = SolverOptions(x) @@ -77,10 +77,6 @@ $( join(map(x -> "- `" * String(x[1]) * "`: " * string(x[2]), CEnum.name_value_p """ Lib.GeneratorStatus @doc """ -$( join(map(x -> "- `" * String(x[1]) * "`: " * string(x[2]), CEnum.name_value_pairs(Lib.BatchOperation)), "\n") ) -""" -Lib.BatchOperation -@doc """ $( join(map(x -> "- `" * String(x[1]) * "`: " * string(x[2]), CEnum.name_value_pairs(Lib.StorageStates)), "\n") ) """ Lib.StorageStates @@ -88,3 +84,7 @@ Lib.StorageStates $( join(map(x -> "- `" * String(x[1]) * "`: " * string(x[2]), CEnum.name_value_pairs(Lib.DSSMessageType)), "\n") ) """ Lib.DSSMessageType +@doc """ +$( join(map(x -> "- `" * String(x[1]) * "`: " * string(x[2]), CEnum.name_value_pairs(Lib.DSSSaveFlags)), "\n") ) +""" +Lib.DSSSaveFlags diff --git a/src/lib.jl b/src/lib.jl index 2c104850..944f0e32 100644 --- a/src/lib.jl +++ b/src/lib.jl @@ -4443,6 +4443,10 @@ function Settings_Set_IterateDisabled(ctx::Ptr{Cvoid}, Value) ccall((:ctx_Settings_Set_IterateDisabled, LIBRARY), Cvoid, (Ptr{Cvoid}, Int32,), ctx, Value) end +function Settings_SetPropertyNameStyle(ctx::Ptr{Cvoid}, Value) + ccall((:ctx_Settings_SetPropertyNameStyle, LIBRARY), Cvoid, (Ptr{Cvoid}, Int32,), ctx, Value) +end + function Solution_Get_Frequency(ctx::Ptr{Cvoid}) ccall((:ctx_Solution_Get_Frequency, LIBRARY), Cdouble, (Ptr{Cvoid},), ctx) end @@ -7159,4 +7163,16 @@ function DSS_Get_CompatFlags() ccall((:DSS_Get_CompatFlags, LIBRARY), UInt32, ()) end -const DSS_CAPI_VERSION = "0.13.4" +function Circuit_ToJSON(ctx::Ptr{Cvoid}, options) + ccall((:ctx_Circuit_ToJSON, LIBRARY), Cstring, (Ptr{Cvoid}, Int32,), ctx, options) +end + +function Circuit_Save(ctx::Ptr{Cvoid}, dirOrFilePath, saveFlags) + ccall((:ctx_Circuit_Save, LIBRARY), Cstring, (Ptr{Cvoid}, Cstring, Int32,), ctx, dirOrFilePath, saveFlags) +end + +function Circuit_FromJSON(ctx::Ptr{Cvoid}, circ, options) + ccall((:ctx_Circuit_FromJSON, LIBRARY), Cstring, (Ptr{Cvoid}, Cstring, Int32,), ctx, circ, options) +end + +const DSS_CAPI_VERSION = "0.14.1" diff --git a/test/circuit.jl b/test/circuit.jl index f99d812e..7006e62d 100644 --- a/test/circuit.jl +++ b/test/circuit.jl @@ -51,5 +51,179 @@ end @test Circuit.YNodeOrder()[end] == "SX3784018A.2" @test Circuit.YCurrents()[end] ≋ 0.032757937074590515 - 0.054281873453359im +Circuit.FromJSON(raw"""{ + "$schema": "https://dss-extensions.org/altdss-schema/2023-12-13.schema.json", + "Name": "4busdybal", + "DefaultBaseFreq": 60.0, + "PreCommands": [ + "Set EarthModel=Carson", + "Set VoltageBases=[ 12.470000000000001 4.1600000000000001]" + ], + "WireData": [ + { + "Name": "conductor", + "RUnits": "mi", + "RAC": 0.306, + "GMRUnits": "ft", + "GMRAC": 0.0244, + "RadUnits": "in", + "Radius": 0.3605, + "NormAmps": 530.0 + }, + { + "Name": "neutral", + "RUnits": "mi", + "RAC": 0.592, + "GMRUnits": "ft", + "GMRAC": 0.00814, + "RadUnits": "in", + "Radius": 0.2815, + "NormAmps": 340.0 + } + ], + "LineGeometry": [ + { + "Name": "4wire", + "NConds": 4, + "NPhases": 3, + "Reduce": true, + "Conductors": [ + "WireData.conductor", + "WireData.conductor", + "WireData.conductor", + "WireData.neutral" + ], + "Units": [ + "ft", + "ft", + "ft", + "ft" + ], + "X": [ + -4.0, + -1.5, + 3.0, + 0.0 + ], + "H": [ + 28.0, + 28.0, + 28.0, + 24.0 + ] + } + ], + "Line": [ + { + "Name": "line1", + "Geometry": "4wire", + "Ratings": [ + 0.0 + ], + "NormAmps": 530.0, + "EmergAmps": 795.0, + "Length": 2000.0, + "Units": "ft", + "Bus1": "sourcebus", + "Bus2": "n2" + }, + { + "Name": "line2", + "Bus1": "n3", + "Bus2": "n4", + "Geometry": "4wire", + "Ratings": [ + 0.0 + ], + "NormAmps": 530.0, + "EmergAmps": 795.0, + "Length": 2500.0, + "Units": "ft" + } + ], + "Vsource": [ + { + "Name": "source", + "Bus1": "sourcebus", + "BasekV": 12.47, + "Phases": 3, + "MVASC3": 200000.0, + "MVASC1": 200000.0 + } + ], + "Load": [ + { + "Name": "load1", + "Phases": 3, + "Bus1": "n4", + "Conn": "wye", + "kV": 4.16, + "kW": 5400.0, + "PF": 0.9, + "Model": 1, + "VMinpu": 0.75 + } + ], + "Transformer": [ + { + "Name": "t1", + "X12": 6.0, + "Bus": [ + "n2", + "n3" + ], + "Conn": [ + "delta", + "wye" + ], + "kV": [ + 12.47, + 4.16 + ], + "kVA": [ + 6000.0, + 6000.0 + ], + "pctR": [ + 0.5, + 0.5 + ] + } + ] +}""", Int32(0)) + +@test Circuit.Name() == "4busdybal" +@test Circuit.NumBuses() == 4 +@test Circuit.NumNodes() == 12 + +# TODO: add JSON.jl as a dependency? +circ = lowercase(Circuit.ToJSON(Int32(0))) + +# check some fragments of the JSON-encoded string +@test occursin("wiredata.neutral", circ) +@test occursin("wiredata.conductor", circ) +@test occursin("4wire", circ) +@test occursin("sourcebus", circ) +@test occursin("set controlmode=static", circ) +@test occursin("set basefrequency=60", circ) + + + +saved = lowercase(Circuit.Save("", + OpenDSSDirect.Lib.DSSSaveFlags_ToString | + OpenDSSDirect.Lib.DSSSaveFlags_SingleFile | + OpenDSSDirect.Lib.DSSSaveFlags_IncludeOptions +)) + +# check some fragments of the DSS script string +@test occursin("wiredata.neutral", saved) +@test occursin("wiredata.conductor", saved) +@test occursin("4wire", saved) +@test occursin("sourcebus", saved) +@test occursin("set controlmode=static", saved) +@test occursin("set basefrequency=60", saved) + + + end # testset diff --git a/test/lines.jl b/test/lines.jl index bd26b03d..d7803e3a 100644 --- a/test/lines.jl +++ b/test/lines.jl @@ -4,9 +4,14 @@ init8500() @testset "Lines" begin +# These three used to get invalid data as the Lines API used the last activated CktElement +# instead of a Line. This was changed in DSS C-API 0.14.0, so no error anymore. We can get +# the old behavior with the compat flag. +Basic.CompatFlags(OpenDSSDirect.Lib.DSSCompatFlags_ActiveLine) @test_throws OpenDSSDirect.OpenDSSDirectException Lines.RMatrix() == reshape([], (0, 0)) @test_throws OpenDSSDirect.OpenDSSDirectException Lines.CMatrix() == reshape([], (0, 0)) @test_throws OpenDSSDirect.OpenDSSDirectException Lines.XMatrix() == reshape([], (0, 0)) +Basic.CompatFlags(UInt32(0)) @test Lines.First() == 1 @test Lines.Next() == 2 From 20df0f5a2d4c937f6e17051e1c931c90b57889f2 Mon Sep 17 00:00:00 2001 From: Paulo Meira <10246101+PMeira@users.noreply.github.com> Date: Sat, 17 Feb 2024 17:27:22 -0300 Subject: [PATCH 3/5] Circuit: add missing type signatures --- src/circuit.jl | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/circuit.jl b/src/circuit.jl index 3b97ca52..d87d662c 100644 --- 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) From fce61f2b0bb500f08a973079ee30380f28b6373d Mon Sep 17 00:00:00 2001 From: Paulo Meira <10246101+PMeira@users.noreply.github.com> Date: Sat, 17 Feb 2024 18:29:36 -0300 Subject: [PATCH 4/5] docs: add logo images --- docs/src/assets/logo-dark.svg | 286 ++++++++++++++++++++++++++++++++++ docs/src/assets/logo.svg | 286 ++++++++++++++++++++++++++++++++++ 2 files changed, 572 insertions(+) create mode 100644 docs/src/assets/logo-dark.svg create mode 100644 docs/src/assets/logo.svg diff --git a/docs/src/assets/logo-dark.svg b/docs/src/assets/logo-dark.svg new file mode 100644 index 00000000..3a504af7 --- /dev/null +++ b/docs/src/assets/logo-dark.svg @@ -0,0 +1,286 @@ + +image/svg+xml diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg new file mode 100644 index 00000000..99db9927 --- /dev/null +++ b/docs/src/assets/logo.svg @@ -0,0 +1,286 @@ + +image/svg+xml From 3bea0cfd8325a2b135048b3d5e1f0e2efb53b0dd Mon Sep 17 00:00:00 2001 From: Paulo Meira <10246101+PMeira@users.noreply.github.com> Date: Sat, 17 Feb 2024 20:55:07 -0300 Subject: [PATCH 5/5] docs: mention `methods`, use only logo in the sidebar. --- docs/make.jl | 13 +++++++------ docs/src/api.md | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 782f5575..3360abf8 100644 --- 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 index 0673034b..84c87881 100644 --- 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