-
-
Notifications
You must be signed in to change notification settings - Fork 402
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: added stats/base/dists/boltzmann/pmf #2108
base: develop
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,159 @@ | ||||||
<!-- | ||||||
|
||||||
@license Apache-2.0 | ||||||
|
||||||
Copyright (c) 2024 The Stdlib Authors. | ||||||
|
||||||
Licensed under the Apache License, Version 2.0 (the "License"); | ||||||
you may not use this file except in compliance with the License. | ||||||
You may obtain a copy of the License at | ||||||
|
||||||
http://www.apache.org/licenses/LICENSE-2.0 | ||||||
|
||||||
Unless required by applicable law or agreed to in writing, software | ||||||
distributed under the License is distributed on an "AS IS" BASIS, | ||||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||||||
See the License for the specific language governing permissions and | ||||||
limitations under the License. | ||||||
|
||||||
--> | ||||||
|
||||||
# Probability Mass Function | ||||||
|
||||||
> [Boltzmann][boltzmann-distribution] distribution probability mass function (PMF). | ||||||
|
||||||
<section class="intro"> | ||||||
|
||||||
The [probability mass function][pmf] (PMF) for a [boltzmann][boltzmann-distribution] random variable is | ||||||
|
||||||
```math | ||||||
f(x; \lambda, N) = P(X=x; \lambda, N) = \begin{cases} | ||||||
\frac{{(\exp(-\lambda k))}{(1-\exp(-\lambda))}}{{(1-\exp(-\lambda N))}} & \text{for } k = 0, 1, 2, \ldots, N \\0 & \text{otherwise} | ||||||
\end{cases} | ||||||
``` | ||||||
|
||||||
where `λ` is the inverse temperature parameter (equal to `1/KbT`) and `N` is the total number of energy states in the system. | ||||||
|
||||||
</section> | ||||||
|
||||||
<!-- /.intro --> | ||||||
|
||||||
<section class="usage"> | ||||||
|
||||||
## Usage | ||||||
|
||||||
```javascript | ||||||
var pmf = require( '@stdlib/stats/base/dists/boltzmann/pmf' ); | ||||||
``` | ||||||
|
||||||
#### pmf( x, λ, N ) | ||||||
|
||||||
Evaluates the [probability mass function][pmf] (PMF) for a [boltzmann][boltzmann-distribution] distribution with total number of energy states `N` and inverse temperature parameter `λ`. | ||||||
|
||||||
```javascript | ||||||
var y = pmf( 1, 0.8, 4 ); | ||||||
// returns ~0.258 | ||||||
|
||||||
y = pmf( 2, 0.8, 4 ); | ||||||
// returns ~0.116 | ||||||
|
||||||
y = pmf( 0, 0.8, 4 ); | ||||||
// returns ~0.574 | ||||||
``` | ||||||
|
||||||
If provided `NaN` as any argument, the function returns `NaN`. | ||||||
|
||||||
```javascript | ||||||
var y = pmf( NaN, 1.5, 5 ); | ||||||
// returns NaN | ||||||
|
||||||
y = pmf( 2, NaN, 5 ); | ||||||
// returns NaN | ||||||
|
||||||
y = pmf( 2, 1.5, NaN ); | ||||||
// returns NaN | ||||||
``` | ||||||
|
||||||
If provided total number if energy states `N` is not a nonnegative integer, the function returns `NaN`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
```javascript | ||||||
var y = pmf( 2, 1.5, 4.5 ); | ||||||
// returns NaN | ||||||
|
||||||
y = pmf( 2, 2.0, -5 ); | ||||||
// returns NaN | ||||||
``` | ||||||
|
||||||
If provided inverse temperature parameter `λ` is not a positive number, the function returns `NaN`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
```javascript | ||||||
var y = pmf( 8, -2.5, 15 ); | ||||||
// returns NaN | ||||||
``` | ||||||
|
||||||
#### pmf.factory( λ, N ) | ||||||
|
||||||
Returns a function for evaluating the [probability mass function][pmf] (PMF) of a [boltzmann][boltzmann-distribution] distribution with total number of energy states `N` and inverse Temperature `λ`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
```javascript | ||||||
var mypmf = pmf.factory( 1.4, 8 ); | ||||||
|
||||||
var y = mypmf( 3 ); | ||||||
// returns ~0.011 | ||||||
|
||||||
y = mypmf( 1 ); | ||||||
// returns ~0.186 | ||||||
``` | ||||||
|
||||||
</section> | ||||||
|
||||||
<!-- /.usage --> | ||||||
|
||||||
<section class="examples"> | ||||||
|
||||||
## Examples | ||||||
|
||||||
<!-- eslint no-undef: "error" --> | ||||||
|
||||||
```javascript | ||||||
var randu = require( '@stdlib/random/base/randu' ); | ||||||
var round = require( '@stdlib/math/base/special/round' ); | ||||||
var pmf = require( '@stdlib/stats/base/dists/boltzmann/pmf' ); | ||||||
|
||||||
var N; | ||||||
var lambda; | ||||||
var x; | ||||||
var y; | ||||||
var i; | ||||||
|
||||||
for ( i = 0; i < 10; i++ ) { | ||||||
N = round( randu() * 20 ); | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use discrete-uniform rather than |
||||||
x = round( randu() * N ); | ||||||
lambda = randu(); | ||||||
y = pmf( x, lambda, N ); | ||||||
console.log( 'x: %d, λ: %d, N: %d, P(X = x;λ,N): %d', x, lambda.toFixed( 4 ), N, y.toFixed( 4 ) ); | ||||||
} | ||||||
``` | ||||||
|
||||||
</section> | ||||||
|
||||||
<!-- /.examples --> | ||||||
|
||||||
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> | ||||||
|
||||||
<section class="related"> | ||||||
|
||||||
</section> | ||||||
|
||||||
<!-- /.related --> | ||||||
|
||||||
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> | ||||||
|
||||||
<section class="links"> | ||||||
|
||||||
[boltzmann-distribution]: https://en.wikipedia.org/wiki/Boltzmann_distribution | ||||||
[pmf]: https://en.wikipedia.org/wiki/Probability_mass_function | ||||||
|
||||||
</section> | ||||||
|
||||||
<!-- /.links --> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
/** | ||
* @license Apache-2.0 | ||
* | ||
* Copyright (c) 2024 The Stdlib Authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
'use strict'; | ||
|
||
// MODULES // | ||
|
||
var bench = require( '@stdlib/bench' ); | ||
var round = require( '@stdlib/math/base/special/round' ); | ||
var randu = require( '@stdlib/random/base/randu' ); | ||
var isnan = require( '@stdlib/math/base/assert/is-nan' ); | ||
var pkg = require( './../package.json' ).name; | ||
var pmf = require( './../lib' ); | ||
|
||
|
||
// MAIN // | ||
|
||
bench( pkg, function benchmark( b ) { | ||
var lambda; | ||
var N; | ||
var x; | ||
var y; | ||
var i; | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
lambda = randu(); | ||
N = round( randu()*20 ); | ||
x = round( randu()*N ); | ||
y = pmf( x, lambda, N ); | ||
if ( isnan( y ) ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( isnan( y ) ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); | ||
|
||
bench( pkg+':factory', function benchmark( b ) { | ||
var lambda; | ||
var mypmf; | ||
var N; | ||
var x; | ||
var i; | ||
var y; | ||
|
||
lambda = randu(); | ||
N = round( randu()*20 ); | ||
mypmf = pmf.factory( lambda, N ); | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
x = round( randu()*N ); | ||
y = mypmf( x ); | ||
if ( isnan( y ) ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( isnan( y ) ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); |
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,80 @@ | ||||||
|
||||||
{{alias}}( x, λ, N ) | ||||||
Evaluates the probability mass function (PMF) for a boltzmann | ||||||
distribution with total number of energy states `N` and inverse | ||||||
temperature analysis `λ` at a value `x`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
If provided `NaN` as any argument, the function returns `NaN`. | ||||||
|
||||||
If provided total number of energy states `N`, inverse temperature | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This sentence is not correct. |
||||||
parameter `λ` or draws `n` which is not a nonnegative integer, | ||||||
the function returns `NaN`. | ||||||
|
||||||
Parameters | ||||||
---------- | ||||||
x: integer | ||||||
Input value. | ||||||
|
||||||
λ: number | ||||||
Inverse temperature parameter. | ||||||
|
||||||
N: integer | ||||||
Total number of energy states. | ||||||
|
||||||
Returns | ||||||
------- | ||||||
out: number | ||||||
Evaluated PMF. | ||||||
|
||||||
Examples | ||||||
-------- | ||||||
> var y = {{alias}}( 1, 0.8, 4 ) | ||||||
~0.258 | ||||||
> y = {{alias}}( 2, 0.8, 4 ) | ||||||
~0.116 | ||||||
> y = {{alias}}( 0, 0.8, 4 ) | ||||||
~0.574 | ||||||
|
||||||
> y = {{alias}}( NaN, 1.5, 5 ) | ||||||
NaN | ||||||
> y = {{alias}}( 2, NaN, 5 ) | ||||||
NaN | ||||||
> y = {{alias}}( 2, 1.5, NaN ) | ||||||
NaN | ||||||
|
||||||
> y = {{alias}}( 2, 1.5, 4.5 ) | ||||||
NaN | ||||||
> y = {{alias}}( 2, 1.5, -2 ) | ||||||
NaN | ||||||
> y = {{alias}}( 2, -1.5, 5 ) | ||||||
NaN | ||||||
|
||||||
|
||||||
{{alias}}.factory( λ, N ) | ||||||
Returns a function for evaluating the probability mass function (PMF) of a | ||||||
boltzmann distribution with total number of energy states `N`, and | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
inverse temperature parameter `λ`. | ||||||
|
||||||
Parameters | ||||||
---------- | ||||||
λ: number | ||||||
Inverse temperature parameter. | ||||||
|
||||||
N: integer | ||||||
Total number of energy states. | ||||||
|
||||||
Returns | ||||||
------- | ||||||
pmf: Function | ||||||
Probability mass function (PMF). | ||||||
|
||||||
Examples | ||||||
-------- | ||||||
> var myPMF = {{alias}}.factory( 1.4, 8 ); | ||||||
> var y = myPMF( 3 ) | ||||||
~0.011 | ||||||
> y = myPMF( 1.0 ) | ||||||
~0.186 | ||||||
|
||||||
See Also | ||||||
-------- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This isn't how we insert equations. You only need to include the HTML comment and then we have build tooling which auto-inserts.