Interface for .NET languages: initial pass

.gitignore

@@ -5,6 +5,7 @@ doc/ctdeploy_key
 *.so
 *.os
 *.pyc
+__pycache__
 *.obj
 *.exe.manifest
 build/

AUTHORS

@@ -21,6 +21,7 @@ Vishesh Devgan (@vdevgan)
 Thomas Fiala (@thomasfiala), Technische Universität München
 David Fronczek
 Mark E. Fuller (@mefuller), Technion
+Sammo Gabay (@Burkenyo)
 Matteo Giani (@MarcDuQuesne)
 Dave Goodwin, California Institute of Technology
 China Hagström (@chinahg), Massachusetts Institute of Technology

CONTRIBUTING.md

@@ -101,3 +101,38 @@
 * Code in `.py` and `.pyx` files needs to be written to work with Python 3
 * The minimum Python version that Cantera supports is Python 3.6, so code should only use features added in Python 3.6 or earlier
 * Please use double quotes in all new Python code
+
+## C#
+
+* C# coding conventions should follow https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions
+* All identifiers should follow the naming conventions in the above document including
+  * Prefixing with `_` for private instance fields (`_foo`, unlike C++)
+  * Prefixing with `s_` for private static fields (`s_bar`), `t_` for private
+    `[ThreadStatic]` fields (`t_baz`).
+  * Initial caps names for class methods (`DoSomething()`, unlike C++)
+* Give the opening brace of a statement block its own line (unlike C++), except empty
+  blocks, which may be written as an `{ }` (for example, a constructor which calls
+  a base-class constructor only).
+* Use only one statement per line.
+* Always use statement blocks (`{ ... }`) for the bodies of statements that can take
+  either a statement block or a single statement (`if`, `for`, etc.)
+* Use file-scoped namespaces in each new file.
+* Do not take any extra Nuget dependencies in the `Cantera.csproj` project.
+* Use C# XML Doc-Comments on types and members, including at least the `<summary>` tag.
+  Always include a doc comment for types, but for members with self-explanatory names,
+  you may omit the doc comment and suppress the build error that would be thrown with
+  `#pragma warning disable/restore CS1591`.
+  * C# doc-comments use `///`, unlike Cantera's preferred use of `//!` for C++
+* Do not expose any code requiring the `unsafe` keyword via a public API
+  (pointers, the `fixed` statement, etc). Pointers are used for the high-performance
+  interop layer with the native Cantera library, but such access should have a
+  “safe” wrapper, such as a `Span<T>` or a managed array.
+* Do not allow exceptions to pass uncaught out of a callback invoked from native code,
+  as the interop layer cannot marshall exceptions between managed and native code,
+  and the process will crash. Use `CallbackException.Register()` within a catch-all
+  block to log the exception for later throwing back in managed code.
+* The primary API for accessing Cantera is the `Application` class, which handles
+  required static initialization of the library. When exposing a new wrapper for CLib
+  functionality, do not expose a public constructor. Rather, mark the constructor
+  `internal` and wrap it in an appropriate factory method in the `Application` class
+  (`public static CreateFoo(string filename) { ... }`).

include/cantera/base/ExternalLogger.h

@@ -0,0 +1,63 @@
+// This file is part of Cantera. See License.txt in the top-level directory or
+// at https://cantera.org/license.txt for license and copyright information.
+
+#ifndef CT_EXTERNAL_LOGGER_H
+#define CT_EXTERNAL_LOGGER_H
+
+#include "logger.h"
+
+namespace Cantera {
+
+//! Logger that delegates to an external source via a callback to produce log output.
+//! @ingroup textlogs
+class ExternalLogger : public Logger
+{
+public:
+    explicit ExternalLogger(LogCallback writer) {
+        if (writer == nullptr) {
+            throw CanteraError("ExternalLogger::ExternalLogger",
+                "Argument “writer” must not be null!");
+        }
+
+        m_writer = writer;
+    }
+
+    void write(const std::string& msg) override {
+        m_writeBuffer.append(msg);
+
+        if (!m_writeBuffer.empty() && m_writeBuffer.back() == '\n') {
+            // This is a bit strange, but the terminal new line is interpreted to mean
+            // “end of message”, so we want to pop it from the message itself.
+            // The other side of the logger will be in charge of deciding whether
+            // “messages” will have a terminal new line or not.
+            m_writeBuffer.pop_back();
+
+            m_writer(LogLevel::INFO, "Info", m_writeBuffer.c_str());
+
+            m_writeBuffer.erase();
+        }
+    }
+
+    void writeendl() override {
+        m_writer(LogLevel::INFO, "Info", m_writeBuffer.c_str());
+
+        m_writeBuffer.erase();
+    }
+
+    void warn(const std::string& warning, const std::string& msg) override {
+        m_writer(LogLevel::WARN, warning.c_str(), msg.c_str());
+    }
+
+    void error(const std::string& msg) override {
+        m_writer(LogLevel::ERROR, "Error", msg.c_str());
+    }
+
+private:
+    std::string m_writeBuffer;
+
+    LogCallback m_writer = nullptr;
+};
+
+}
+
+#endif

include/cantera/clib/clib_defs.h

@@ -36,4 +36,11 @@
 # define DERR -999.999
 #endif
 
+// Used by external logger
+enum LogLevel { INFO, WARN , ERROR };
+
+//! Represents a callback that is invoked to produce log output.
+typedef void
+    (*LogCallback)(enum LogLevel logLevel, const char* category, const char* message);
+
 #endif

include/cantera/clib/ct.h

@@ -77,6 +77,7 @@ extern "C" {
     CANTERA_CAPI int thermo_getEntropies_R(int n, size_t lenm, double* s_r);
     CANTERA_CAPI int thermo_getCp_R(int n, size_t lenm, double* cp_r);
     CANTERA_CAPI int thermo_setElectricPotential(int n, double v);
+    CANTERA_CAPI int thermo_set_TP(int n, double* vals);
     CANTERA_CAPI int thermo_set_RP(int n, double* vals);
     CANTERA_CAPI int thermo_set_HP(int n, double* vals);
     CANTERA_CAPI int thermo_set_UV(int n, double* vals);
@@ -155,6 +156,7 @@ extern "C" {
 
     CANTERA_CAPI int ct_getCanteraError(int buflen, char* buf);
     CANTERA_CAPI int ct_setLogWriter(void* logger);
+    CANTERA_CAPI int ct_setLogCallback(LogCallback writer);
     CANTERA_CAPI int ct_addCanteraDirectory(size_t buflen, const char* buf);
     CANTERA_CAPI int ct_getDataDirectories(int buflen, char* buf, const char* sep);
     CANTERA_CAPI int ct_getCanteraVersion(int buflen, char* buf);

interfaces/dotnet/.gitignore

@@ -0,0 +1,37 @@
+*.swp
+*.*~
+project.lock.json
+.DS_Store
+*.pyc
+nupkg/
+
+# Visual Studio Code
+.vscode
+
+# Rider
+.idea
+
+# User-specific files
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+x64/
+x86/
+build/
+bld/
+[Bb]in/
+[Oo]bj/
+[Oo]ut/
+msbuild.log
+msbuild.err
+msbuild.wrn
+
+# Visual Studio 2015
+.vs/

interfaces/dotnet/Cantera.Tests/Cantera.Tests.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net6.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- We need the following three dependencies to support unit testing -->
+    <!-- This dependency provides the test runner -->
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.3.0" />
+    <!-- This dependency provideds the xunit annotations and assertions -->
+    <PackageReference Include="xunit" Version="2.4.2" />
+    <!-- This depenedency connects xunit to the test runner for both dotnet CLI and VisualStudio -->
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+
+    <!-- This dependency provides code coverage analysis -->
+    <PackageReference Include="coverlet.collector" Version="3.1.2">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+
+    <ProjectReference Include="../Cantera/Cantera.csproj" />
+  </ItemGroup>
+
+</Project>

interfaces/dotnet/Cantera.Tests/src/ApplicationTest.cs

@@ -0,0 +1,166 @@
+// This file is part of Cantera. See License.txt in the top-level directory or
+// at https://cantera.org/license.txt for license and copyright information.
+
+using System.Reflection;
+using System.Text.RegularExpressions;
+using Cantera.Interop;
+using Xunit;
+
+namespace Cantera.Tests;
+
+[Collection("Application")]
+public class ApplicationTest
+{
+    class FooException : Exception { }
+
+    readonly static LogMessageEventArgs s_mockLog =
+        new(LogLevel.Warning, "Testing", "This is a test message.");
+
+    [Fact]
+    public void CanteraInfo_VersionRetrieved()
+    {
+        // version string should start with a number
+        Assert.Matches("^[1-9]", Application.Version);
+    }
+
+    [Fact]
+    public void CanteraInfo_GitCommitRetrieved()
+    {
+        Assert.NotEmpty(Application.GitCommit);
+    }
+
+    [Fact]
+    public void CanteraInfo_DataDirectoryAdded()
+    {
+        var dirs = Application.DataDirectories;
+        var originalCount = dirs.Count;
+        var longestDir = dirs.MaxBy(d => d.FullName.Length);
+
+        Assert.NotNull(longestDir);
+
+        dirs.Add(Path.Join(longestDir!.FullName, "garbazh"));
+
+        Assert.Equal(originalCount + 1, dirs.Count);
+    }
+
+    [Fact]
+    public void LogWriter_MessageLogged()
+    {
+        LogLevel? logLevel = null;
+        string? report = null;
+
+        void LogMessage(object? sender, LogMessageEventArgs e)
+        {
+            logLevel = e.LogLevel;
+            report = e.Message;
+        }
+
+        try
+        {
+            Application.MessageLogged += LogMessage;
+
+            ProduceRealLogOutput();
+
+            Assert.NotNull(logLevel);
+            Assert.NotNull(report);
+
+            Assert.Equal(LogLevel.Info, logLevel);
+            Assert.NotEmpty(report);
+        }
+        finally
+        {
+            Application.MessageLogged -= LogMessage;
+        }
+    }
+
+    [Fact]
+    public void LogWriter_ConsoleLogged()
+    {
+        var stdOut = Console.Out;
+        var consoleOut = new StringWriter();
+
+        try
+        {
+            Console.SetOut(consoleOut);
+            Application.AddConsoleLogging();
+            ProduceMockLogOutput();
+
+            var output = consoleOut.ToString();
+
+            var logLevel = s_mockLog.LogLevel.ToString().ToUpperInvariant();
+
+            var prefix = $"{logLevel} ({s_mockLog.Category}) ";
+            const string iso8601FormatString = "yyyy-MM-ddThh:mm:ss.fffzzz";
+            const int lengthOfIso8601FormattedString = 29;
+
+            Assert.Matches('^' + Regex.Escape(prefix), output);
+
+            var nowString = output.Substring(
+                prefix.Length, lengthOfIso8601FormattedString);
+
+            Assert.True(DateTimeOffset.TryParseExact(
+                nowString, iso8601FormatString, null, default, out _));
+        }
+        finally
+        {
+            Application.RemoveConsoleLogging();
+            Console.SetOut(stdOut);
+        }
+    }
+
+    [Fact]
+    public void LogWriter_ExceptionRegistered()
+    {
+        static void LogMessage(object? sender, LogMessageEventArgs e) =>
+            throw new FooException();
+
+        try
+        {
+            Application.MessageLogged += LogMessage;
+
+            var thrown =
+                Assert.Throws<CallbackException>(() => ProduceMockLogOutput());
+
+            Assert.NotNull(thrown.InnerException);
+            Assert.IsType<FooException>(thrown.InnerException);
+        }
+        finally
+        {
+            Application.MessageLogged -= LogMessage;
+        }
+    }
+
+    /// <summary>
+    /// Produces log output by calling into the native Cantera library to invoke
+    /// the logging callback.
+    /// </summary>
+    static void ProduceRealLogOutput()
+    {
+        using var thermo = Application.CreateThermoPhase("gri30.yaml");
+
+        var handle = (ThermoPhaseHandle) typeof(ThermoPhase)
+            .GetField("_handle", BindingFlags.NonPublic | BindingFlags.Instance)!
+            .GetValue(thermo)!;
+
+        InteropUtil.CheckReturn(LibCantera.thermo_print(handle, InteropConsts.True, 0));
+    }
+
+    /// <summary>
+    /// Produces log output without calling into the native Cantera library.
+    /// </summary>
+    static void ProduceMockLogOutput()
+    {
+        var eventField = typeof(Application).GetField("s_invokeMessageLoggedDelegate",
+            BindingFlags.Static | BindingFlags.NonPublic);
+
+        Assert.NotNull(eventField);
+
+        var del = (LibCantera.LogCallback) eventField!.GetValue(null)!;
+
+        Assert.NotNull(del);
+
+        del(s_mockLog.LogLevel, s_mockLog.Category, s_mockLog.Message);
+
+        CallbackException.ThrowIfAny();
+    }
+}