Merge pull request #184 from dsyme/d10

Placeholders for documentation

Author: dsyme

Directory.Build.props

@@ -4,6 +4,7 @@
 
      <LibTorchNugetVersion>1.5.6</LibTorchNugetVersion>
      <TorchSharpVersion>0.3.52267</TorchSharpVersion>
+	 <FSharpCoreVersion>4.7.2</FSharpCoreVersion>
       <!-- Standard nuget.org location -->
     <RestoreSources>https://api.nuget.org/v3/index.json</RestoreSources>
 
@@ -23,7 +24,7 @@
         https://donsyme.pkgs.visualstudio.com/TorchSharp/_packaging/packages2/nuget/v3/index.json
     </RestoreSources>
     -->
-    <OtherFlags>--warnon:1182 $(OtherFlags)</OtherFlags>
+    <OtherFlags>--warnon:1182 --warnon:3390 $(OtherFlags)</OtherFlags>
   </PropertyGroup>
 
   <PropertyGroup>

bundles/DiffSharp-cpu/DiffSharp-cpu.fsproj

@@ -13,6 +13,7 @@
     <ProjectReference Include="..\..\src\DiffSharp.Backends.Torch\DiffSharp.Backends.Torch.fsproj" />
     <!--  reference a libtorch runtime redist -->
     <PackageReference Include="libtorch-cpu" Version="$(LibTorchNugetVersion)" />
+	<PackageReference Update="FSharp.Core" Version="$(FSharpCoreVersion)" />
   </ItemGroup>
 
 </Project>

bundles/DiffSharp-lite/DiffSharp-lite.fsproj

@@ -12,6 +12,7 @@
     <ProjectReference Include="..\..\src\DiffSharp.Core\DiffSharp.Core.fsproj" />
     <ProjectReference Include="..\..\src\DiffSharp.Backends.Reference\DiffSharp.Backends.Reference.fsproj" />
     <ProjectReference Include="..\..\src\DiffSharp.Backends.Torch\DiffSharp.Backends.Torch.fsproj" />
+	<PackageReference Update="FSharp.Core" Version="$(FSharpCoreVersion)" />
   </ItemGroup>
 
 </Project>

src/DiffSharp.Backends.Reference/DiffSharp.Backends.Reference.fsproj

@@ -10,6 +10,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\DiffSharp.Core\DiffSharp.Core.fsproj" />
+	<PackageReference Update="FSharp.Core" Version="$(FSharpCoreVersion)" />
   </ItemGroup>
 
 </Project>

src/DiffSharp.Backends.Torch/DiffSharp.Backends.Torch.fsproj

@@ -11,6 +11,7 @@
   <ItemGroup>
     <ProjectReference Include="..\DiffSharp.Core\DiffSharp.Core.fsproj" />
     <PackageReference Include="TorchSharp" Version="$(TorchSharpVersion)" />
+	<PackageReference Update="FSharp.Core" Version="$(FSharpCoreVersion)" />
   </ItemGroup>
 
 </Project>

src/DiffSharp.Core/DiffSharp.Core.fsproj

@@ -15,5 +15,6 @@
     <Compile Include="Data.fs" />
     <Compile Include="Model.fs" />
     <Compile Include="Optim.fs" />
+	<PackageReference Update="FSharp.Core" Version="$(FSharpCoreVersion)" />
   </ItemGroup>
 </Project>

src/DiffSharp.Core/DiffSharp.fs

@@ -17,60 +17,118 @@ module internal Utils =
 
 
 [<AbstractClass>]
+/// <summary>TBD</summary>
 type Distribution<'T>() =
+
+    /// <summary>TBD</summary>
     abstract member sample: unit -> 'T
+
+    /// <summary>TBD</summary>
     abstract member logprob: 'T -> Tensor
 
 
 [<AbstractClass>]
+/// <summary>TBD</summary>
 type TensorDistribution() =
     inherit Distribution<Tensor>()
+
+    /// <summary>TBD</summary>
     member d.sample(numSamples:int) = Array.init numSamples (fun _ -> d.sample()) |> dsharp.stack
+
+    /// <summary>TBD</summary>
     abstract member batchShape: int[]
+
+    /// <summary>TBD</summary>
     abstract member eventShape: int[]
+
+    /// <summary>TBD</summary>
     abstract member mean: Tensor
+
+    /// <summary>TBD</summary>
     abstract member stddev: Tensor
+
+    /// <summary>TBD</summary>
     abstract member variance: Tensor
+
     default d.stddev = d.variance.sqrt()
     default d.variance = d.stddev * d.stddev
+
+    /// <summary>TBD</summary>
     member d.prob(value) = d.logprob(value).exp()
 
 
+/// <summary>TBD</summary>
 type Normal(mean:Tensor, stddev:Tensor) =
     inherit TensorDistribution()
     do if mean.shape <> stddev.shape then failwithf "Expecting mean and standard deviation with same shape, received %A, %A" mean.shape stddev.shape
     do if mean.dim > 1 then failwithf "Expecting scalar parameters (0-dimensional mean and stddev) or a batch of scalar parameters (1-dimensional mean and stddev)"
+
+    /// <summary>TBD</summary>
     override d.batchShape = d.mean.shape
+
+    /// <summary>TBD</summary>
     override d.eventShape = [||]
+
+    /// <summary>TBD</summary>
     override d.mean = mean
+
+    /// <summary>TBD</summary>
     override d.stddev = stddev
+
+    /// <summary>TBD</summary>
     override d.sample() = d.mean + dsharp.randnLike(d.mean) * d.stddev
+
+    /// <summary>TBD</summary>
     override d.logprob(value) = 
         if value.shape <> d.batchShape then failwithf "Expecting a value with shape %A, received %A" d.batchShape value.shape
         let v = value - d.mean in -(v * v) / (2. * d.variance) - (log d.stddev) - logSqrt2Pi
+
+    /// <summary>TBD</summary>
     override d.ToString() = sprintf "Normal(mean:%A, stddev:%A)" d.mean d.stddev
 
 
+/// <summary>TBD</summary>
 type Uniform(low:Tensor, high:Tensor) =
     inherit TensorDistribution()
     do if low.shape <> high.shape then failwithf "Expecting low and high with same shape, received %A, %A" low.shape high.shape
     do if low.dim > 1 then failwithf "Expecting scalar parameters (0-dimensional low and high) or a batch of scalar parameters (1-dimensional low and high)"
+
+    /// <summary>TBD</summary>
     member d.low = low
+
+    /// <summary>TBD</summary>
     member d.high = high
+
+    /// <summary>TBD</summary>
     member d.range = high - low
+
+    /// <summary>TBD</summary>
     override d.batchShape = low.shape
+
+    /// <summary>TBD</summary>
     override d.eventShape = [||]
+
+    /// <summary>TBD</summary>
     override d.mean = (low + high) / 2.
+
+    /// <summary>TBD</summary>
     override d.variance = d.range * d.range / 12.
+
+    /// <summary>TBD</summary>
     override d.sample() = d.low + dsharp.randLike(d.low) * d.range
+
+    /// <summary>TBD</summary>
     override d.logprob(value) = 
         if value.shape <> d.batchShape then failwithf "Expecting a value with shape %A, received %A" d.batchShape value.shape
         let lb = low.le(value).cast(low.dtype)
         let ub = high.gt(value).cast(high.dtype)
         log (lb * ub) - log d.range
+
+    /// <summary>TBD</summary>
     override d.ToString() = sprintf "Uniform(low:%A, high:%A)" d.low d.high
 
 
+/// <summary>TBD</summary>
 type Bernoulli(?probs:Tensor, ?logits:Tensor) =
     inherit TensorDistribution()
     let _probs, _logits, _dtype =
@@ -79,20 +137,39 @@ type Bernoulli(?probs:Tensor, ?logits:Tensor) =
         | Some p, None -> let pp = p.float() in clampProbs pp, probsToLogits pp true, p.dtype  // Do not normalize probs
         | None, Some lp -> let lpp = lp.float() in logitsToProbs lpp true, lpp, lp.dtype  // Do not normalize logits
         | None, None -> failwithf "Expecting either probs or logits"
+
+    /// <summary>TBD</summary>
     member d.probs = _probs.cast(_dtype)
+
+    /// <summary>TBD</summary>
     member d.logits = _logits.cast(_dtype)
+
+    /// <summary>TBD</summary>
     override d.batchShape = d.probs.shape
+
+    /// <summary>TBD</summary>
     override d.eventShape = [||]
+
+    /// <summary>TBD</summary>
     override d.mean = d.probs
+
+    /// <summary>TBD</summary>
     override d.variance = (_probs * (1. - _probs)).cast(_dtype)
+
+    /// <summary>TBD</summary>
     override d.sample() = dsharp.bernoulli(_probs).cast(_dtype)
+
+    /// <summary>TBD</summary>
     override d.logprob(value) =
         if value.shape <> d.batchShape then failwithf "Expecting a value with shape %A, received %A" d.batchShape value.shape
         let lp = (_probs ** value) * ((1. - _probs) ** (1. - value))  // Correct but numerical stability can be improved
         lp.log().cast(_dtype)
+
+    /// <summary>TBD</summary>
     override d.ToString() = sprintf "Bernoulli(probs:%A)" d.probs
 
 
+/// <summary>TBD</summary>
 type Categorical(?probs:Tensor, ?logits:Tensor) =
     inherit TensorDistribution()
     let _probs, _logits, _dtype =
@@ -102,13 +179,29 @@ type Categorical(?probs:Tensor, ?logits:Tensor) =
         | None, Some lp -> let lpp = (lp - lp.logsumexp(-1, keepDim=true)).float() in logitsToProbs lpp false, lpp, lp.dtype  // Normalize logits
         | None, None -> failwithf "Expecting either probs or logits"    
     do if _probs.dim < 1 || _probs.dim > 2 then failwithf "Expecting vector parameters (1-dimensional probs or logits) or batch of vector parameters (2-dimensional probs or logits), received shape %A" _probs.shape
+
+    /// <summary>TBD</summary>
     member d.probs = _probs.cast(_dtype)
+
+    /// <summary>TBD</summary>
     member d.logits = _logits.cast(_dtype)
+
+    /// <summary>TBD</summary>
     override d.batchShape = if d.probs.dim = 1 then [||] else [|d.probs.shape.[0]|]
+
+    /// <summary>TBD</summary>
     override d.eventShape = [||]
+
+    /// <summary>TBD</summary>
     override d.mean = dsharp.onesLike(d.probs) * System.Double.NaN
+
+    /// <summary>TBD</summary>
     override d.stddev = dsharp.onesLike(d.probs) * System.Double.NaN
+
+    /// <summary>TBD</summary>
     override d.sample() = dsharp.multinomial(_probs, 1).cast(_dtype).squeeze()
+
+    /// <summary>TBD</summary>
     override d.logprob(value) =
         if value.shape <> d.batchShape then failwithf "Expecting a value with shape %A, received %A" d.batchShape value.shape
         if d.batchShape.Length = 0 then
@@ -118,9 +211,12 @@ type Categorical(?probs:Tensor, ?logits:Tensor) =
             let is = value.int().toArray() :?> int[]
             let lp = Array.init d.batchShape.[0] (fun i -> _logits.[i, is.[i]]) |> dsharp.stack
             lp.cast(_dtype)
+
+    /// <summary>TBD</summary>
     override d.ToString() = sprintf "Categorical(probs:%A)" d.probs
 
 
+/// <summary>TBD</summary>
 type Empirical<'T when 'T:equality>(values:seq<'T>, ?weights:Tensor, ?logWeights:Tensor, ?combineDuplicates:bool) =
     inherit Distribution<'T>()
     let _categorical, _weighted =
@@ -156,25 +252,49 @@ type Empirical<'T when 'T:equality>(values:seq<'T>, ?weights:Tensor, ?logWeights
             _values <- newValues
             _categorical <- Categorical(logits=newLogWeights)
         _weighted <- not (Seq.allEqual (_categorical.probs.unstack()))
+
+    /// <summary>TBD</summary>
     member d.values = _values
+
+    /// <summary>TBD</summary>
     member d.valuesTensor = _valuesTensor.Force()
+
+    /// <summary>TBD</summary>
     member d.length = d.values.Length
+
+    /// <summary>TBD</summary>
     member d.weights = _categorical.probs
+
+    /// <summary>TBD</summary>
     member d.logWeights = _categorical.logits
+
+    /// <summary>TBD</summary>
     member d.isWeighted = _weighted
+
+    /// <summary>TBD</summary>
     member d.Item
         with get(i) = d.values.[i], d.weights.[i]
+
+    /// <summary>TBD</summary>
     member d.GetSlice(start, finish) =
         let start = defaultArg start 0
         let finish = defaultArg finish d.length - 1
         Empirical(d.values.[start..finish], logWeights=d.logWeights.[start..finish])
+
+    /// <summary>TBD</summary>
     member d.unweighted() = Empirical(d.values)
+
+    /// <summary>TBD</summary>
     member d.map (f:'T->'a) = Empirical(Array.map f d.values, logWeights=d.logWeights)
+
+    /// <summary>TBD</summary>
     member d.filter (predicate:'T->bool) =
         let results = ResizeArray<'T*Tensor>()
         Array.iteri (fun i v -> if predicate v then results.Add(v, d.logWeights.[i])) d.values
         let v, lw = results.ToArray() |> Array.unzip
         Empirical(v, logWeights=dsharp.stack(lw))
+
+    /// <summary>TBD</summary>
     member d.sample(?minIndex:int, ?maxIndex:int) = // minIndex is inclusive, maxIndex is exclusive
         let minIndex = defaultArg minIndex 0
         let maxIndex = defaultArg maxIndex d.length
@@ -185,7 +305,11 @@ type Empirical<'T when 'T:equality>(values:seq<'T>, ?weights:Tensor, ?logWeights
             d.[minIndex..maxIndex].sample()
         else
             let i = _categorical.sample() |> int in d.values.[i]
+
+    /// <summary>TBD</summary>
     member d.resample(numSamples, ?minIndex:int, ?maxIndex:int) = Array.init numSamples (fun _ -> d.sample(?minIndex=minIndex, ?maxIndex=maxIndex)) |> Empirical
+
+    /// <summary>TBD</summary>
     member d.thin(numSamples, ?minIndex:int, ?maxIndex:int) = 
         if d.isWeighted then failwithf "Cannot thin weighted distribution. Consider transforming Empirical to an unweigted Empirical by resampling."
         let minIndex = defaultArg minIndex 0
@@ -196,23 +320,50 @@ type Empirical<'T when 'T:equality>(values:seq<'T>, ?weights:Tensor, ?logWeights
             let v = d.values.[i]
             results.Add(v)
         Empirical(results.ToArray())
+
+    /// <summary>TBD</summary>
     member d.combineDuplicates() = Empirical(d.values, logWeights=d.logWeights, combineDuplicates=true)
+
+    /// <summary>TBD</summary>
     member d.expectation (f:Tensor->Tensor) =
         if d.isWeighted then d.valuesTensor.unstack() |> Seq.mapi (fun i v -> d.weights.[i]*(f v)) |> dsharp.stack |> dsharp.sum(0)
         else d.valuesTensor.unstack() |> Seq.map f |> dsharp.stack |> dsharp.mean(0)
+
+    /// <summary>TBD</summary>
     member d.mean = d.expectation(id)
+
+    /// <summary>TBD</summary>
     member d.variance = let mean = d.mean in d.expectation(fun x -> (x-mean)**2)
+
+    /// <summary>TBD</summary>
     member d.stddev = dsharp.sqrt(d.variance)
+
+    /// <summary>TBD</summary>
     member d.mode =
         if d.isWeighted then 
             let dCombined = d.combineDuplicates()
             let i = dCombined.logWeights.argmax() in dCombined.values.[i.[0]]
         else
             let vals, _ = d.values |> Array.getUniqueCounts true
             vals.[0]
+
+    /// <summary>TBD</summary>
     member d.min = d.valuesTensor.min()
+
+    /// <summary>TBD</summary>
     member d.max = d.valuesTensor.max()
+
+    /// <summary>TBD</summary>
     member d.effectiveSampleSize = 1. / d.weights.pow(2).sum()
+
+    /// <summary>TBD</summary>
     override d.sample() = d.sample(minIndex=0, maxIndex=d.length)
+
+    /// <summary>TBD</summary>
     override d.logprob(_) = failwith "Not supported"  // TODO: can be implemented using density estimation
-    override d.ToString() = sprintf "Empirical(length:%A)" d.length
+
+    /// <summary>TBD</summary>
+
+    /// <summary>TBD</summary>
+    override d.ToString() = sprintf "Empirical(length:%A)" d.length
+