Von Mises Distribution

doc/distributions/dist_reference.qbk

@@ -38,6 +38,7 @@
 [include students_t.qbk]
 [include triangular.qbk]
 [include uniform.qbk]
+[include von_mises.qbk]
 [include weibull.qbk]
 [endsect] [/section:dists Distributions]
 

doc/distributions/von_mises.qbk

@@ -0,0 +1,102 @@
+[/ 
+  Copyright 2022 Matt Borland.
+  Distributed under the Boost Software License, Version 1.0.
+  (See accompanying file LICENSE_1_0.txt or copy at
+  http://www.boost.org/LICENSE_1_0.txt).
+]
+
+[section:von_mises_dist Von Mises Distribution]
+
+
+``#include <boost/math/distributions/von_mises.hpp>``
+
+   namespace boost{ namespace math{
+    template <typename RealType = double, 
+              typename ``__Policy``   = ``__policy_class`` >
+    class von_mises_distribution;
+
+    using von_mises = von_mises_distribution<>;
+
+    template <typename RealType, typename ``__Policy``>
+    class von_mises_distribution
+    {
+    public:
+       using value_type = RealType;
+       using policy_type = Policy;
+
+       von_mises_distribution(RealType mean = 0, RealType concentration = 1); // Constructor.
+          : m_mean {maen}, m_conc {concentration} // Default is standard von_mises distribution.
+       // Accessor functions.
+       RealType mean() const;
+       RealType concentration() const;
+       RealType location() const;
+       RealType scale() const;
+    }; // class von_mises_distribution
+
+   }} // namespaces
+
+The [@https://en.wikipedia.org/wiki/Von_Mises_distribution von Mises distribution], also known as a the circular normal distribution,
+is a continuous probability distribution on a circle.
+
+[h4 Member Functions]
+
+   von_mises_distribution(RealType mean = 0, RealType concentration = 1); ;
+
+Constructs a [@https://en.wikipedia.org/wiki/Von_Mises_distribution 
+von Mises Distribution] with mean /mean/, and concentration /concentration/.
+
+Requires that the /mean/ and /concentration/ parameters are both finite;
+otherwise if infinity or NaN then calls __domain_error.
+
+   RealType mean() const;
+
+Returns the /mean/ parameter of this distribution.
+
+   RealType concentration() const;
+
+Returns the /concentration/ parameter of this distribution.
+
+    RealType location() const;
+
+Returns the /mean/ parameter as the location is synonymous but used in some definitions.
+
+    RealType scale() const;
+
+Returns the /concentration/ parameter as the location is synonymous but used in some definitions.
+
+[h4 Non-member Accessors]
+
+All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
+that are generic to all distributions are supported: __usual_accessors.
+
+The domain of the random variable is O <= x <= 2[pi].
+
+[h4 Accuracy]
+
+The CDF of this distribution is not analytic so an approximation is made.
+For the accuracy on your specific platform please run reporting/accuracy/von_mises_ulps.cpp
+
+An example on Apple M1 Pro is below using double precsision calculations:
+
+*PDF with concentration of 4*
+
+[$../images/von_mises_ulps_pdf_4d.svg]
+
+*PDF with concentration of 64*
+
+[$../images/von_mises_ulps_pdf_64d.svg]
+
+*CDF with concentration of 4*
+
+[$../images/von_mises_ulps_cdf_4d.svg]
+
+*CDF with concentration of 64*
+
+[$../images/von_mises_ulps_cdf_64d.svg]
+
+[h4 References]
+* [@https://en.wikipedia.org/wiki/Von_Mises_distribution Wikipedia von Mises distribution]
+* [@https://mathworld.wolfram.com/vonMisesDistribution.html Weisstein, Eric W. "von Mises Distribution." From MathWorld--A Wolfram Web Resource.]
+* [@https://dl.acm.org/doi/pdf/10.1145/355744.355753]
+
+[endsect] [/section:von_mises_dist Von Mises]

include/boost/math/distributions/detail/common_error_handling.hpp

@@ -11,6 +11,8 @@
 
 #include <boost/math/policies/error_handling.hpp>
 #include <boost/math/special_functions/fpclassify.hpp>
+#include <boost/math/constants/constants.hpp>
+
 // using boost::math::isfinite;
 // using boost::math::isnan;
 
@@ -96,6 +98,26 @@ inline bool check_location(
    return true;
 }
 
+
+template <class RealType, class Policy>
+inline bool check_angle(
+      const char* function,
+      RealType angle,
+      RealType* result,
+      const Policy& pol)
+{
+   if(!(boost::math::isfinite)(angle)
+       || angle < -boost::math::constants::pi<RealType>() 
+       || angle > +boost::math::constants::pi<RealType>())
+   {
+      *result = policies::raise_domain_error<RealType>(
+         function,
+         "Angle parameter is %1%, but must be between -pi and +pi!", angle, pol);
+      return false;
+   }
+   return true;
+}
+
 template <class RealType, class Policy>
 inline bool check_x(
       const char* function,

include/boost/math/distributions/fwd.hpp

@@ -117,6 +117,9 @@ class uniform_distribution;
 template <class RealType, class Policy>
 class weibull_distribution;
 
+template <class RealType, class Policy>
+class von_mises_distribution;
+
 }} // namespaces
 
 #define BOOST_MATH_DECLARE_DISTRIBUTIONS(Type, Policy)\
@@ -152,6 +155,7 @@ class weibull_distribution;
    typedef boost::math::students_t_distribution<Type, Policy> students_t;\
    typedef boost::math::triangular_distribution<Type, Policy> triangular;\
    typedef boost::math::uniform_distribution<Type, Policy> uniform;\
-   typedef boost::math::weibull_distribution<Type, Policy> weibull;
+   typedef boost::math::weibull_distribution<Type, Policy> weibull; \
+   typedef boost::math::von_mises_distribution<Type, Policy> von_mises;
 
 #endif // BOOST_MATH_DISTRIBUTIONS_FWD_HPP