Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/numeric/special functions/assoc legendre"

From cppreference.com
(mention Condon-Shortley)
m (→‎Notes: turned the list into a table.)
 
(14 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{cpp/title|assoc_legendre|assoc_legendref|assoc_legendrel}}
 
{{cpp/title|assoc_legendre|assoc_legendref|assoc_legendrel}}
−
{{cpp/numeric/special_math/navbar}}
+
{{cpp/numeric/special_functions/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl |num=1|since=c++17|
+
{{dcl header|cmath}}
−
double      assoc_legendre( unsigned int n, unsigned int m, double x );
+
{{dcl rev multi|num=1|since1=c++17|dcl1=
−
double      assoc_legendre( unsigned int n, unsigned int m, float x );
+
float      assoc_legendre ( unsigned int n, unsigned int m, float x );
−
double     assoc_legendre( unsigned int n, unsigned int m, long double x );
+
double      assoc_legendre ( unsigned int n, unsigned int m, double x );
 +
long double assoc_legendre ( unsigned int n, unsigned int m, long double x );
 +
|since2=c++23|dcl2=
 +
/* floating-point-type */ assoc_legendre( unsigned int n, unsigned int m,
 +
                                          /* floating-point-type */ x );
 +
}}
 +
{{dcl|num=2|since=c++17|
 
float      assoc_legendref( unsigned int n, unsigned int m, float x );
 
float      assoc_legendref( unsigned int n, unsigned int m, float x );
 +
}}
 +
{{dcl|num=3|since=c++17|
 
long double assoc_legendrel( unsigned int n, unsigned int m, long double x );
 
long double assoc_legendrel( unsigned int n, unsigned int m, long double x );
 
}}
 
}}
−
{{dcl |num=2|since=c++17|
+
{{dcl h|[[#Notes|Additional overloads]]}}
−
double      assoc_legendre( unsigned int n, unsigned int m, Integral x );
+
{{dcl header|cmath}}
 +
{{dcl|num=A|since=c++17|
 +
template< class Integer >
 +
double      assoc_legendre ( unsigned int n, unsigned int m, Integer x );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
@1@ Computes the [[enwiki:Associated_Legendre_polynomials|associated Legendre polynomials]] of the degree {{tt|n}}, order {{tt|m}}, and argument {{tt|x}}
+
@1-3@ Computes the {{enwiki|Associated Legendre polynomials}} of the degree {{c|n}}, order {{c|m}}, and argument {{c|x}}.{{rev inl|since=c++23| The library provides overloads of {{tt|std::assoc_legendre}} for all cv-unqualified floating-point types as the type of the parameter {{c|x}}.}}
−
@4@ A set of overloads or a function template accepting an argument of any [[cpp/types/is_integral|integral type]]. Equivalent to {{v|1}} after casting the argument to {{c|double}}.
+
@A@ Additional overloads are provided for all integer types, which are treated as {{c/core|double}}.
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | n | the degree of the polynomial, a value of unsigned integer type}}
+
{{par|n|the degree of the polynomial, an unsigned integer value}}
−
{{par | m | the order of the polynomial, a value of unsigned integer type}}
+
{{par|m|the order of the polynomial, an unsigned integer value}}
−
{{par | x | the argument, a value of a floating-point or integral type}}
+
{{par|x|the argument, a floating-point or integer value}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
If no errors occur, value of the associated Legendre polynomial {{math|P{{su|p=m|b=n}}}} of {{tt|x}}, that is {{math|(1-x{{su|p=2}}){{su|p=m/2}} {{mfrac|d{{su|p=m}}|dx{{su|p=m}}}}P{{su|b=n}}(x)}}, is returned (where {{math|P{{su|b=n}}(x)}} is the unassociated Legendre polynomial, {{c|std::legendre(n, x)}}).
+
If no errors occur, value of the associated Legendre polynomial {{mathjax-or|1=\(\mathsf{P}_n^m\)|2=P{{su|p=m|b=n}}}} of {{c|x}}, that is {{mathjax-or|1=\((1 - x^2) ^ {m/2} \: \frac{ \mathsf{d} ^ m}{ \mathsf{d}x ^ m} \, \mathsf{P}_n(x)\)|2=(1-x{{su|p=2}}){{su|p=m/2}} {{mfrac|d{{su|p=m}}|dx{{su|p=m}}}}P{{su|b=n}}(x)}}, is returned (where {{mathjax-or|1=\(\mathsf{P}_n(x)\)|2=P{{su|b=n}}(x)}} is the unassociated Legendre polynomial, {{c|std::legendre(n, x)}}).
  
−
Note that the Condon-Shortley phase term {{math|(-1){{su|p=m}}}} is omitted from this definition.
+
Note that the [https://mathworld.wolfram.com/Condon-ShortleyPhase.html Condon-Shortley phase term] {{mathjax-or|1=\((-1)^m\)|2=(-1){{su|p=m}}}} is omitted from this definition.
  
 
===Error handling===
 
===Error handling===
 
Errors may be reported as specified in [[cpp/numeric/math/math_errhandling|math_errhandling]]
 
Errors may be reported as specified in [[cpp/numeric/math/math_errhandling|math_errhandling]]
−
 
 
* If the argument is NaN, NaN is returned and domain error is not reported
 
* If the argument is NaN, NaN is returned and domain error is not reported
 
* If {{math|{{!}}x{{!}} > 1}}, a domain error may occur
 
* If {{math|{{!}}x{{!}} > 1}}, a domain error may occur
−
* If {{tt|n}} is greater or equal to 128, the behavior is implementation-defined.
+
* If {{tt|n}} is greater or equal to 128, the behavior is implementation-defined
  
 
===Notes===
 
===Notes===
−
{{cpp/numeric/special_math/older_impl_note}}
+
{{cpp/numeric/special functions/older impl note}}
  
−
An implementation of this function is also [http://www.boost.org/doc/libs/release/libs/math/doc/html/math_toolkit/sf_poly/legendre.html available in boost.math] as {{tt|boost::math::legendre_p}}, except that the boost.math definition includes the Condon-Shortley phase term.
+
An implementation of this function is also [https://www.boost.org/doc/libs/release/libs/math/doc/html/math_toolkit/sf_poly/legendre.html available in boost.math] as {{tt|boost::math::legendre_p}}, except that the boost.math definition includes the Condon-Shortley phase term.
  
 
The first few associated Legendre polynomials are:
 
The first few associated Legendre polynomials are:
−
* assoc_legendre(0, 0, x) {{=}} 1
+
 
−
* assoc_legendre(1, 0, x) {{=}} {{math|x}}
+
{| class="wikitable" style="font-size:95%; text-align:center;"
−
* assoc_legendre(1, 1, x) {{=}} {{math|-(1-x{{su|p=2}}){{su|p=1/2}}}}
+
|-
−
* assoc_legendre(2, 0, x) {{=}} {{math|{{mfrac|1|2}}(3x{{su|p=2}}-1)}}
+
! Function
−
* assoc_legendre(2, 1, x) {{=}} {{math|-3x(1-x{{su|p=2}}){{su|p=1/2}}}}
+
! Polynomial
−
* assoc_legendre(2, 2, x) {{=}} {{math|3(1-x{{su|p=2}})}}
+
|- style="height:45px;"
 +
| {{nbsp|4}}{{co|1=assoc_legendre(0, 0, x)}}{{nbsp|4}} || 1
 +
|- style="height:45px;"
 +
| {{co|1=assoc_legendre(1, 0, x)}} || {{math|x}}
 +
|- style="height:45px;"
 +
| {{co|1=assoc_legendre(1, 1, x)}} || {{math|(1 - x{{su|p=2}}){{su|p=1/2}}}}
 +
|- style="height:45px;"
 +
| {{co|1=assoc_legendre(2, 0, x)}} || {{math|{{mfrac|1|2}}(3x{{su|p=2}} - 1)}}
 +
|- style="height:45px;"
 +
| {{co|1=assoc_legendre(2, 1, x)}} || {{nbsp|4}}{{math|3x(1 - x{{su|p=2}}){{su|p=1/2}}}}{{nbsp|4}}
 +
|- style="height:45px;"
 +
| {{co|1=assoc_legendre(2, 2, x)}} || {{math|3(1 - x{{su|p=2}})}}
 +
|}
 +
 
 +
{{cpp/numeric/special functions/additional integer overload note|assoc_legendre}}
  
 
===Example===
 
===Example===
−
{{example|code=
+
{{example
 +
|code=
 
#include <cmath>
 
#include <cmath>
 
#include <iostream>
 
#include <iostream>
−
double P20(double x) { return 0.5*(3*x*x-1); }
+
 
−
double P21(double x) { return -3.0*x*std::sqrt(1-x*x); }
+
double P20(double x)
−
double P22(double x) { return 3*(1-x*x); }
+
{
 +
    return 0.5 * (3 * x * x - 1);
 +
}
 +
 
 +
double P21(double x)
 +
{
 +
    return 3.0 * x * std::sqrt(1 - x * x);
 +
}
 +
 
 +
double P22(double x)
 +
{
 +
    return 3 * (1 - x * x);
 +
}
 +
 
 
int main()
 
int main()
 
{
 
{
Line 65: Line 103:
 
|output=
 
|output=
 
-0.125=-0.125
 
-0.125=-0.125
−
-1.29904=-1.29904
+
1.29904=1.29904
 
2.25=2.25
 
2.25=2.25
 
}}
 
}}
Line 71: Line 109:
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/numeric/special_math/dsc legendre}}
+
{{dsc inc|cpp/numeric/special functions/dsc legendre}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===External links===
 
===External links===
−
[http://mathworld.wolfram.com/AssociatedLegendrePolynomial.html Weisstein, Eric W. "Associated Legendre Polynomial."] From MathWorld--A Wolfram Web Resource.
+
{{eli|[https://mathworld.wolfram.com/AssociatedLegendrePolynomial.html Weisstein, Eric W. "Associated Legendre Polynomial."] From MathWorld &mdash; A Wolfram Web Resource.}}
  
−
[[de:cpp/numeric/special_math/assoc_legendre]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/numeric/special_math/assoc_legendre]]
+
−
[[fr:cpp/numeric/special_math/assoc_legendre]]
+
−
[[it:cpp/numeric/special_math/assoc_legendre]]
+
−
[[ja:cpp/numeric/special_math/assoc_legendre]]
+
−
[[pt:cpp/numeric/special_math/assoc_legendre]]
+
−
[[ru:cpp/numeric/special_math/assoc_legendre]]
+
−
[[zh:cpp/numeric/special_math/assoc_legendre]]
+

Latest revision as of 14:07, 22 March 2023

 
C++
 
Numerics library
Common mathematical functions
Mathematical special functions (C++17)
Mathematical constants (C++20)
Basic linear algebra algorithms (C++26)
Floating-point environment (C++11)
Complex numbers
Numeric array (valarray)
Pseudo-random number generation
Factor operations
(C++17)
(C++17)
Interpolations
(C++20)
(C++20)
Saturation arithmetic
(C++26)
(C++26)
(C++26)
(C++26)
(C++26)

Generic numeric operations
Bit operations
(C++20)    
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++23)
(C++20)
 
Mathematical special functions
 
Defined in header <cmath>
(1)
float       assoc_legendre ( unsigned int n, unsigned int m, float x );

double      assoc_legendre ( unsigned int n, unsigned int m, double x );

long double assoc_legendre ( unsigned int n, unsigned int m, long double x );
 (since C++17)
(until C++23)
/* floating-point-type */ assoc_legendre( unsigned int n, unsigned int m,
                                          /* floating-point-type */ x );
 (since C++23)
float       assoc_legendref( unsigned int n, unsigned int m, float x );
 (2) (since C++17)
long double assoc_legendrel( unsigned int n, unsigned int m, long double x );
 (3) (since C++17)
Defined in header <cmath>
template< class Integer >
double      assoc_legendre ( unsigned int n, unsigned int m, Integer x );
 (A) (since C++17)
1-3) Computes the Associated Legendre polynomials of the degree n, order m, and argument x. The library provides overloads of std::assoc_legendre for all cv-unqualified floating-point types as the type of the parameter x.(since C++23)
A) Additional overloads are provided for all integer types, which are treated as double.

Contents

[edit] Parameters

n - the degree of the polynomial, an unsigned integer value
m - the order of the polynomial, an unsigned integer value
x - the argument, a floating-point or integer value

[edit] Return value

If no errors occur, value of the associated Legendre polynomial Pmn of x, that is (1-x2)m/2
dm
dxm
Pn(x), is returned (where Pn(x) is the unassociated Legendre polynomial, std::legendre(n, x)).

Note that the Condon-Shortley phase term (-1)m is omitted from this definition.

[edit] Error handling

Errors may be reported as specified in math_errhandling

  • If the argument is NaN, NaN is returned and domain error is not reported
  • If |x| > 1, a domain error may occur
  • If n is greater or equal to 128, the behavior is implementation-defined

[edit] Notes

Implementations that do not support C++17, but support ISO 29124:2010, provide this function if __STDCPP_MATH_SPEC_FUNCS__ is defined by the implementation to a value at least 201003L and if the user defines __STDCPP_WANT_MATH_SPEC_FUNCS__ before including any standard library headers.

Implementations that do not support ISO 29124:2010 but support TR 19768:2007 (TR1), provide this function in the header tr1/cmath and namespace std::tr1.

An implementation of this function is also available in boost.math as boost::math::legendre_p, except that the boost.math definition includes the Condon-Shortley phase term.

The first few associated Legendre polynomials are:

Function Polynomial
    assoc_legendre(0, 0, x)     1
assoc_legendre(1, 0, x) x
assoc_legendre(1, 1, x) (1 - x2)1/2
assoc_legendre(2, 0, x)
1
2
(3x2 - 1)
assoc_legendre(2, 1, x)     3x(1 - x2)1/2    
assoc_legendre(2, 2, x) 3(1 - x2)

The additional overloads are not required to be provided exactly as (A). They only need to be sufficient to ensure that for their argument num of integer type, std::assoc_legendre(int_num1, int_num2, num) has the same effect as std::assoc_legendre(int_num1, int_num2, static_cast<double>(num)).

[edit] Example

Run this code
#include <cmath>
#include <iostream>
 
double P20(double x)
{
    return 0.5 * (3 * x * x - 1);
}
 
double P21(double x)
{
    return 3.0 * x * std::sqrt(1 - x * x);
}
 
double P22(double x)
{
    return 3 * (1 - x * x);
}
 
int main()
{
    // spot-checks
    std::cout << std::assoc_legendre(2, 0, 0.5) << '=' << P20(0.5) << '\n'
              << std::assoc_legendre(2, 1, 0.5) << '=' << P21(0.5) << '\n'
              << std::assoc_legendre(2, 2, 0.5) << '=' << P22(0.5) << '\n';
}

Output: 

-0.125=-0.125
1.29904=1.29904
2.25=2.25

[edit] See also

(C++17)(C++17)(C++17)
 Legendre polynomials
(function) [edit]

[edit] External links

Weisstein, Eric W. "Associated Legendre Polynomial." From MathWorld — A Wolfram Web Resource.
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/special_functions/assoc_legendre&oldid=149536"