feat: add Belief and BeliefSet

Aplib.Core/Belief/Belief.cs

@@ -0,0 +1,79 @@
+using System;
+
+namespace Aplib.Core.Belief
+{
+    /// <summary>
+    /// The <see cref="Belief{TReference, TResource}"/> class represents a belief.
+    /// Some <i>object reference</i> is used to generate/update a <i>resource</i> 
+    /// (i.e., some piece of information on the game state as perceived by an agent).
+    /// </summary>
+    /// <remarks>
+    /// It implements the <see cref="IBelief"/> interface.
+    /// It supports implicit conversion to <typeparamref name="TResource"/>.
+    /// </remarks>
+    /// <typeparam name="TReference">The type of the reference used to generate/update the resource.</typeparam>
+    /// <typeparam name="TResource">The type of the resource the belief represents.</typeparam>
+    public class Belief<TReference, TResource> : IBelief
+    {
+        /// <summary>
+        /// The reference used to generate/update the resource.
+        /// </summary>
+        private readonly TReference _reference;
+
+        /// <summary>
+        /// A function that takes a reference and generates/updates a resource.
+        /// </summary>
+        private readonly Func<TReference, TResource> _getResourceFromReference;
+
+        /// <summary>
+        /// A function that sets a condition on when the resource should be updated.
+        /// </summary>
+        private readonly Func<bool> _updateIf = () => true;
+
+        /// <summary>
+        /// The resource represented by the belief (i.e., some piece of information on the game state as perceived by an agent).
+        /// </summary>
+        private TResource _resource;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Belief{TReference, TResource}"/> class with a reference, 
+        /// and a function to generate/update the resource using the reference.
+        /// </summary>
+        /// <param name="reference">The reference used to generate/update the resource.</param>
+        /// <param name="getResourceFromReference">A function that takes a reference and generates/updates a resource.</param>
+        public Belief(TReference reference, Func<TReference, TResource> getResourceFromReference)
+        {
+            _reference = reference;
+            _getResourceFromReference = getResourceFromReference;
+            _resource = _getResourceFromReference(_reference);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Belief{TReference, TResource}"/>
+        /// </summary>
+        /// <param name="reference">The reference used to generate/update the resource.</param>
+        /// <param name="getResourceFromReference">A function that takes a reference and generates/updates a resource.</param>
+        /// <param name="updateIf">A function that sets a condition on when the resource should be updated.</param>
+        public Belief(TReference reference, Func<TReference, TResource> getResourceFromReference, Func<bool> updateIf)
+            : this(reference, getResourceFromReference)
+        {
+            _updateIf = updateIf;
+        }
+
+        /// <summary>
+        /// Implicit conversion operator to allow a <see cref="Belief{TReference, TResource}"/> object 
+        /// to be used where a <typeparamref name="TResource"/> is expected.
+        /// </summary>
+        /// <param name="belief">The <see cref="Belief{TReference, TResource}"/> object to convert.</param>
+        public static implicit operator TResource(Belief<TReference, TResource> belief) => belief._resource;
+
+        /// <summary>
+        /// Generates/updates the resource if the updateIf condition is satisfied.
+        /// The resource is then updated by calling the getResourceFromReference function.
+        /// </summary>
+        public void UpdateBelief()
+        {
+            if (_updateIf()) _resource = _getResourceFromReference(_reference);
+        }
+    }
+}

Aplib.Core/Belief/Beliefset.cs

@@ -0,0 +1,40 @@
+using System.Linq;
+
+namespace Aplib.Core.Belief
+{
+    /// <summary>
+    /// The <see cref="BeliefSet"/> class can be inherited to define a set of beliefs for an agent.
+    /// </summary>
+    /// <remarks>
+    /// All <i>public fields</i> of type <see cref="IBelief"/> that are defined in the inheriting class
+    /// are automatically updated when calling <see cref="UpdateBeliefs"/>.
+    /// </remarks>
+    public abstract class BeliefSet
+    {
+        private readonly IBelief[] _beliefs;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="BeliefSet"/> class.
+        /// </summary>
+        /// <remarks>
+        /// All <i>public fields</i> of type <see cref="IBelief"/> that are defined in the inheriting class
+        /// are automatically updated when calling <see cref="UpdateBeliefs"/>.
+        /// </remarks>
+        protected BeliefSet()
+        {
+            _beliefs =
+                GetType().GetFields()
+                .Where(field => typeof(IBelief).IsAssignableFrom(field.FieldType))
+                .Select(field => (IBelief)field.GetValue(this))
+                .ToArray();
+        }
+
+        /// <summary>
+        /// Updates all objects of type <see cref="IBelief"/> that are defined as <i>public fields</i> in <see cref="BeliefSet"/>.
+        /// </summary>
+        public void UpdateBeliefs()
+        {
+            foreach (IBelief belief in _beliefs) belief.UpdateBelief();
+        }
+    }
+}

Aplib.Core/Belief/IBelief.cs

@@ -0,0 +1,16 @@
+namespace Aplib.Core.Belief
+{
+    /// <summary>
+    /// The <see cref="IBelief"/> interface defines a contract for classes that represent a belief.
+    /// </summary>
+    /// <remarks>
+    /// A belief is some piece of information on the game state as perceived by an agent.
+    /// </remarks>
+    public interface IBelief
+    {
+        /// <summary>
+        /// Updates the belief based on information of the game state.
+        /// </summary>
+        void UpdateBelief();
+    }
+}

Aplib.Tests/Core/Belief/BeliefTests.cs

@@ -0,0 +1,93 @@
+using Aplib.Core.Belief;
+
+namespace Aplib.Tests.Core.Belief;
+public class BeliefTests
+{
+    private static TReference ID<TReference>(TReference reference) => reference;
+
+    private static int GetCount<T>(IEnumerable<T> reference) => reference.Count();
+
+    private static bool TrueUpdateIf() => true;
+
+    private static bool FalseUpdateIf() => false;
+
+
+    /// <summary>
+    /// Given a Belief instance,
+    /// When it is assigned to a variable of its resource type,
+    /// Then it is implicitly converted to its resource type.
+    /// </summary>
+    [Fact]
+    public void Belief_AssignedToResourceType_IsImplicitlyConvertedToResourceType()
+    {
+        // Arrange
+        string reference = "def";
+        Belief<string, string> belief = new(reference, ID);
+
+        // Act
+        string resource = belief;
+
+        // Assert
+        Assert.Equal("def", resource);
+    }
+
+    /// <summary>
+    /// Given a Belief instance with an updateIf condition that is satisfied,
+    /// When UpdateBelief is called,
+    /// Then the resource is updated.
+    /// </summary>
+    [Fact]
+    public void UpdateBelief_UpdateIfConditionIsSatisfied_UpdatesResource()
+    {
+        // Arrange
+        List<int> list = [];
+        Belief<List<int>, int> belief = new(list, GetCount, TrueUpdateIf);
+
+        // Act
+        list.Add(69);
+        belief.UpdateBelief();
+
+        // Assert
+        Assert.Equal(1, belief);
+    }
+
+    /// <summary>
+    /// Given a Belief instance with an updateIf condition that is not satisfied,
+    /// When UpdateBelief is called,
+    /// Then the resource is not updated.
+    /// </summary>
+    [Fact]
+    public void UpdateBelief_UpdateIfConditionIsNotSatisfied_DoesNotUpdateResource()
+    {
+        // Arrange
+        List<int> list = [];
+        Belief<List<int>, int> belief = new(list, GetCount, FalseUpdateIf);
+
+        // Act
+        list.Add(69);
+        belief.UpdateBelief();
+
+        // Assert
+        Assert.Equal(0, belief);
+    }
+
+    /// <summary>
+    /// Given a Belief instance with a reference,
+    /// When the reference is assigned to and UpdateBelief is called,
+    /// Then the resource is not updated.
+    /// </summary>
+    [Fact]
+    public void UpdateBelief_ReferenceIsAssignedTo_DoesNotUpdateResource()
+    {
+        // Arrange
+        string def = "def";
+        Belief<string, string> belief = new(def, ID, TrueUpdateIf);
+
+        // Act
+        def = "abc";
+        belief.UpdateBelief();
+
+        // Assert
+        Assert.NotEqual(def, belief);
+    }
+}

Aplib.Tests/Core/Belief/BeliefsetTests.cs

@@ -0,0 +1,43 @@
+using Aplib.Core.Belief;
+
+namespace Aplib.Tests.Core.Belief;
+public class BeliefsetTests
+{
+    /// <summary>
+    /// Given a Beliefset instance with multiple beliefs,
+    /// When UpdateBeliefs is called,
+    /// Then all beliefs are updated.
+    /// </summary>
+    [Fact]
+    public void UpdateBeliefs_Called_UpdatesAllBeliefs()
+    {
+        // Arrange
+        TestBeliefset beliefset = new();
+
+        // Act
+        beliefset.UpdateBeliefs();
+
+        // Assert
+        Assert.True(beliefset.Belief1.Updated);
+        Assert.True(beliefset.Belief2.Updated);
+    }
+
+    private class TestBeliefset : Beliefset
+    {
+        public SimpleBelief Belief1 = new();
+        public SimpleBelief Belief2 = new();
+    }
+
+    /// <summary>
+    /// A simple belief that can be used to test whether <see cref="UpdateBelief"/> has been called.
+    /// </summary>
+    private class SimpleBelief : IBelief
+    {
+        public bool Updated { get; private set; } = false;
+
+        public void UpdateBelief()
+        {
+            Updated = true;
+        }
+    }
+}