Update examples, changelog, README for version 0.14.0

SVN ref:

git-svn-id: https://svn.code.sf.net/p/electricdss/code/trunk@3723 d8739450-1e93-4ef4-a0af-c327d92816ff

Author: PMeira

README.md

@@ -12,7 +12,7 @@ This library exposes the OpenDSS/OpenDSS-PM v9+ engine in a plain C interface th
 Through the other projects under DSS-Extensions, DSS C-API enables projects to use the OpenDSS in multiple platforms (Windows, Linux, macOS) across multiple architectures (Intel x86, x86-64, ARM32, and ARM64, including Apple's M1 and M2). Most of the features added to this based library is shared across all other projects. If you need support for a language not listed below, please open a new issue (either here or in https://github.com/dss-extensions/dss-extensions/issues) and we will evaluate that language.
 
 <p align="center">
-    <img alt="Overview of related repositories" src="https://raw.githubusercontent.com/dss-extensions/dss_capi/master/docs/images/repomap.png" width=600>
+    <img alt="Overview of related repositories" src="https://raw.githubusercontent.com/dss-extensions/dss-extensions/main/images/repomap.png" width=600>
 </p>
 
 If you are looking for the bindings to other languages:
@@ -23,11 +23,11 @@ If you are looking for the bindings to other languages:
 - [DSS MATLAB](http://github.com/dss-extensions/dss_matlab/) presents multi-platform integration (Windows, Linux, MacOS) with DSS C-API and is also very compatible with the API of the official OpenDSS COM classes.
 - [dss.hpp](https://dss-extensions.org/dss_capi/): header-only library for C++, also hosped in this repository (`include/` directory). Allows using DSS C-API more comfortably from C++, abstract away memory management and low-level details such as API conventions of the DSS C-API library. Currently uses Eigen and fmt.
 
-Version 0.13.x is based on OpenDSS revision 3619 (exactly OpenDSS v9.6.1.2), with many extra/custom features.
+Version 0.14.x is based on OpenDSS revision 3723 (exactly OpenDSS v9.8.0.1), with many extra/custom features.
 
 **For the source-code of a specific version, check the Git tags or the Releases page.**
 
-While the main objective of COM compatibility has been reached, this is still a work-in-progress and is subject to changes. Especially, there are planned changes targeting version 0.14, which will become v1.0 when we consider it ready.
+While the main objective of COM compatibility has been reached, this is still a work-in-progress and is subject to changes. Especially, there are planned changes targeting version 1.0.
 
 Instead of using extra numeric parameters as in the official DDLL interface ("OpenDSSDirect" or "DCSL"), each original COM property is exposed as a pair of functions. For example, the load kVA property is exposed as:
 
@@ -46,7 +46,7 @@ Since 2019-03-05, the `dss_capi` repository contains all the Pascal code used to
 
 See [the changelog](https://github.com/dss-extensions/dss_capi/blob/master/docs/changelog.md) for a detailed list.
 
-- 2023-12-13 / version 0.14.0b1: Beta release for 0.14.0. Lots of changes and bugfixes, see the changelog.
+- 2024-02-09 / version 0.14.0: Lots of changes and bugfixes, see the changelog. 
 - 2023-06-27 / version 0.13.4: Bugfix release (CapControl), incremental improvements. See the changelog or release page for details.
 - 2023-06-11 / version 0.13.3: Bugfix release for some components (notably Capacitor, Reactor, UPFC).
 - 2023-05-24 / version 0.13.2: Minor release, includes updates to JSON exports, some more error-checking, internal code refactoring, header updates, and minor ports from the official OpenDSS.

docs/changelog.md

@@ -15,12 +15,13 @@
     - i18n complements
     - drop the `ctx_` prefix for most functions, leave the DSSContext API as the default version. We plan to drop the current single-instance API, but we can add a header with inline C functions, prefixed, for easier migration. 
 
+# Versions 0.14.x
 
-## Version 0.14.0
+## Version 0.14.0 (2024-02-09)
 
-Starting on this version, we will call DSS C-API and related projects AltDSS, an alternative implementation of OpenDSS, to make it more clear that this is not supported by EPRI and many extra features are not present in the official OpenDSS. Watch the DSS-Extensions org on GitHub for more announcements soon, including some support for the official implementation (still Windows-only at the moment).
+Starting on this version, we will call DSS C-API and related projects AltDSS, an alternative implementation of OpenDSS, to make it more clear that this is not supported by EPRI and many extra features are not present in the official OpenDSS. Watch the DSS-Extensions org on GitHub for more announcements soon, including some support for the official implementation (still Windows-only at the moment). The name change **does not** mean compatibility or other aspects are expected to change, the project will still follow the basic guidelines of compatibility that have been followed since 2018.
 
-This version should match OpenDSS v9.7.1.1 (SVN r3646). Remember to check the compatibility flags and [Known differences](https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md). Other recent SVN commits, up to r3717 (dated 2023-12-11), either do not update code or are not relevant for the implementation on AltDSS/DSS C-API.
+This version should match OpenDSS v9.8.0.1 (SVN r3723). Remember to check the compatibility flags and [Known differences](https://github.com/dss-extensions/dss_capi/blob/master/docs/known_differences.md).
 
 - Another large internal (Pascal) code refactoring step and general clean-up. Check the commits for details, too many to list. A last step is under progress and will be merged in the next major release.
 
@@ -39,6 +40,7 @@ This version should match OpenDSS v9.7.1.1 (SVN r3646). Remember to check the co
 - **Introduce "Setter" flags.** These are flags used to tweak how the property update is done. Notably,`AvoidFullRecalc` (some other flags are only using by the engine, internally): some specific properties like `Load.kW` can be updated both directly through a DSS script (or Text interface), or through the dedicated Loads API in any of the specific language bindings of the many APIs. The dedicated API does not force a YPrim update and full load model recalculation. 
     - When using this flag `AvoidFullRecalc` in the Obj/Batch APIs, the behavior will follow the dedicated Loads API.
     - Other flags include `ImplicitSizes` and `AllowAllConductors`. Both are currently used for enabling some of the JSON Schema functionally.
+    - For batch operations, `SkipNA` was introduced to allow handling scenarios with non-uniform data.
     - The relevant API functions were updated to include an extra function argument with the setter flags.
     - Is this `AvoidFullRecalc` the same as `SkipSideEffects` compat flag? **No.** `AvoidFullRecalc` is still valid and by design (including some behavior listed in OpenDSS docs), whereas `SkipSideEffects` is potentially unintended behavior.
 
@@ -52,12 +54,15 @@ This version should match OpenDSS v9.7.1.1 (SVN r3646). Remember to check the co
 
 - **New** Alt and Obj families of functions. A new family of functions was added to allow most legacy API operations and new functionality directly on objects and batches, instead of relying on "active..." idiom. A new package, **AltDSS-Python**, will be published to illustrate the new approach. Since the engine is shared, users can mix both approach (e.g. use AltDSS-Python and OpenDSSDirect.py in the same script).
 
-- Batch/API: allow using batches with simple functions that return float64/int32 for each object.
+- Batch/API: 
+    - Allow using batches with simple functions that return float64/int32 for each object.
+    - Allow using `INT32_MAX` and `NaN` for missing values, which can be skipped with the `SetterFlags_SkipNA` flag. Sooner or later, there should a better alternative, but this can be useful in the time being.
 
 - Headers: 
     - Remove `stdint_compat.h`. This was only required for very old or non-standard compiler like MSVC 2008. Users that require that can still source the file from older releases or get similar files from other sources.
     - Include `stddef.h` when building as C code.
     - Mark `CktElement_Get_IsIsolated` with `(API Extension)`
+    - Add more `const` qualifiers. Especially useful for the new Rust and Golang bindings.
 
 - Specific bug fixes:
     - AutoTrans: fix `DumpProperties`, readd `bank` property (unused internally).
@@ -81,6 +86,7 @@ This version should match OpenDSS v9.7.1.1 (SVN r3646). Remember to check the co
 
 - Misc:
     - Error handling: add a few numeric checks, and check for errors in more places during solution algorithms. The changes should help finding issues earlier and/or more easily.
+    - Check for null pointers (usually missing circuit solution) in a few more places.
     - Properties/capitalization: adjust capitalization of nearly all property names. Use lowercase for description keys (help strings). *Feedback on the capitalization is welcome.* As a reminder, OpenDSS is case-insensitive, but other other are not. Providing a better internal representation of the properties will help other tools to use the internal names without extra work (no need for each tool to adjust capitalization), and it doesn't affect the DSS engine itself nor compatibility with the upstream OpenDSS.
     - Obj/API: introduce `ExtraClassIDs` to get some special lists.
     - Classic to Obj/Alt API bridge: add many `*_Get_Pointer` functions (e.g. `CktElement_Get_Pointer`, `Loads_Get_Pointer`). These functions return a pointer that can be used in the Obj API. This should enable an easier migration from the classic API, or allow users to use the Obj API to complement the classic API where the latter is lacking.

examples/ctx_openmp.c

@@ -61,10 +61,10 @@ int main(void)
         }
 
         // Get total for the register "Zone Losses kWh" (index 12)
-        int32_t count[2] = {0, 0};
+        int32_t dims[4] = {0, 0, 0, 0};
         double *totals = NULL;
         ctx_Meters_Get_First(ctx);
-        ctx_Meters_Get_Totals(ctx, &totals, count);
+        ctx_Meters_Get_Totals(ctx, &totals, dims);
         kWh_losses += totals[12];
         DSS_Dispose_PDouble(&totals);
     }

examples/minimal_classic.c

@@ -6,7 +6,7 @@ int main(void)
 {
     // For numVoltages, first `int` is the current count, 
     // the second `int` is the allocated capacity.
-    int numVoltages[2] = {0, 0}; 
+    int numVoltages[4] = {0, 0, 0, 0}; 
     double *voltages = NULL;
     int numNodes;
     int i;

examples/minimal_gr.c

@@ -8,10 +8,10 @@ int main(void)
     double** data_PDouble;
     int32_t** data_PInteger;
     int8_t** data_PByte;
-    int32_t* count_PPAnsiChar;
-    int32_t* count_PDouble;
-    int32_t* count_PInteger;
-    int32_t* count_PByte;
+    int32_t* dims_PPAnsiChar;
+    int32_t* dims_PDouble;
+    int32_t* dims_PInteger;
+    int32_t* dims_PByte;
 
     double* voltages;
     int numNodes;
@@ -23,24 +23,24 @@ int main(void)
         &data_PDouble,
         &data_PInteger,
         &data_PByte,
-        &count_PPAnsiChar,
-        &count_PDouble,
-        &count_PInteger,
-        &count_PByte
+        &dims_PPAnsiChar,
+        &dims_PDouble,
+        &dims_PInteger,
+        &dims_PByte
     );
 
     Text_Set_Command("compile master.dss");
     Solution_Solve();
     Circuit_Get_AllBusVolts_GR();
 
     // The result for Circuit_Get_AllBusVolts is now in 
-    // dataPtr_PDouble[0] and countPtr_PDouble
+    // dataPtr_PDouble[0] and dims_PDouble
 
     // Copy just the pointer for convenience, the GR mechanism
     // in Pascal is responsible for the allocated memory.
     voltages = data_PDouble[0];
 
-    numNodes = count_PDouble[0]/2;
+    numNodes = dims_PDouble[0]/2;
     if (numNodes == 0)
     {
         return -1;

src/Executive/ExecHelper.pas

@@ -935,7 +935,6 @@ procedure ShowAnyHelp(DSS: TDSSContext; cmd: ArrayOfString; const opt: String; c
 begin
     if Length(opt) < 1 then
     begin
-        Writeln('if Length(opt) < 1 then');
         lst := TStringList.Create;
         for i := 0 to High(cmd) do
             lst.Add(PadRight(cmd[i], colwidth));