# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.0 `sort` Chapter.
``sort`` - Sorting and Searching
This module is concerned with sorting and searching numeric or character data.
It handles only the simplest types of data structure and it is concerned only with **internal** sorting and searching -- that is, sorting and searching a set of data which can all be stored within the program.
If you have large files of data or complicated data structures to be sorted or searched you should use a comprehensive sorting or searching program or package.
Functionality Index
-------------------
**Ranking**
arbitrary data: :meth:`arbitrary_rank`
columns of a matrix
integer numbers: :meth:`intmat_rank_columns`
real numbers: :meth:`realmat_rank_columns`
rows of a matrix
integer numbers: :meth:`intmat_rank_rows`
real numbers: :meth:`realmat_rank_rows`
vector
character data: :meth:`charvec_rank`
integer numbers: :meth:`intvec_rank`
real numbers: :meth:`realvec_rank`
**Rearranging (according to pre-determined ranks)**
vector
character data: :meth:`charvec_rank_rearrange`
complex numbers: :meth:`cmplxvec_rank_rearrange`
integer numbers: :meth:`intvec_rank_rearrange`
real numbers: :meth:`realvec_rank_rearrange`
**Searching (i.e., exact match or the nearest lower value)**
binary search
vector
integer numbers: :meth:`intvec_search`
real numbers: :meth:`realvec_search`
strings: :meth:`charvec_search`
direct search
vector
real numbers: :meth:`realvec_vec_search`
**Service functions**
check validity of a permutation: :meth:`permute_check`
decompose a permutation into cycles: :meth:`permute_decompose`
invert a permutation (ranks to indices or vice versa): :meth:`permute_invert`
**Sorting (i.e., rearranging into sorted order)**
quick sort
vector
character data: :meth:`charvec_sort`
integer numbers: :meth:`intvec_sort`
real numbers: :meth:`realvec_sort`
For full information please refer to the NAG Library document
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01intro.html
"""
# NAG Copyright 2017-2024.
[docs]def realvec_sort(rv, m1, order):
r"""
``realvec_sort`` rearranges a vector of `float` numbers into ascending or descending order.
.. _m01ca-py2-py-doc:
For full information please refer to the NAG Library document for m01ca
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01caf.html
.. _m01ca-py2-py-parameters:
**Parameters**
**rv** : float, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{rv}` must contain `float` values to be sorted.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{rv}` to be sorted.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the values will be sorted into ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**rv** : float, ndarray, shape :math:`\left(\textit{m2}\right)`
These values are rearranged into sorted order.
.. _m01ca-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01ca-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
``realvec_sort`` is based on Singleton's implementation of the 'median-of-three' Quicksort algorithm (see Singleton (1969)), but with two additional modifications.
First, small subfiles are sorted by an insertion sort on a separate final pass (see Sedgewick (1978)).
Second, if a subfile is partitioned into two very unbalanced subfiles, the larger of them is flagged for special treatment: before it is partitioned, its end points are swapped with two random points within it; this makes the worst case behaviour extremely unlikely.
.. _m01ca-py2-py-references:
**References**
Sedgewick, R, 1978, `Implementing Quicksort programs`, Comm. ACM (21), 847--857
Singleton, R C, 1969, `An efficient algorithm for sorting with minimal storage: Algorithm 347`, Comm. ACM (12), 185--187
"""
raise NotImplementedError
[docs]def intvec_sort(iv, m1, order):
r"""
``intvec_sort`` rearranges a vector of integer numbers into ascending or descending order.
.. _m01cb-py2-py-doc:
For full information please refer to the NAG Library document for m01cb
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01cbf.html
.. _m01cb-py2-py-parameters:
**Parameters**
**iv** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{iv}` must contain integer values to be sorted.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{iv}` to be sorted.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the values will be sorted into ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**iv** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
These values are rearranged into sorted order.
.. _m01cb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01cb-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``intvec_sort`` is based on Singleton's implementation of the 'median-of-three' Quicksort algorithm (see Singleton (1969)), but with two additional modifications.
First, small subfiles are sorted by an insertion sort on a separate final pass (see Sedgewick (1978)) Second, if a subfile is partitioned into two very unbalanced subfiles, the larger of them is flagged for special treatment: before it is partitioned, its end points are swapped with two random points within it; this makes the worst case behaviour extremely unlikely.
.. _m01cb-py2-py-references:
**References**
Sedgewick, R, 1978, `Implementing Quicksort programs`, Comm. ACM (21), 847--857
Singleton, R C, 1969, `An efficient algorithm for sorting with minimal storage: Algorithm 347`, Comm. ACM (12), 185--187
"""
raise NotImplementedError
[docs]def charvec_sort(ch, m1, l1, l2, order):
r"""
``charvec_sort`` rearranges a vector of character data so that a specified substring is in ASCII or reverse ASCII order.
.. _m01cc-py2-py-doc:
For full information please refer to the NAG Library document for m01cc
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ccf.html
.. _m01cc-py2-py-parameters:
**Parameters**
**ch** : str, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{ch}` must contain character data to be sorted.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{ch}` to be sorted.
**l1** : int
Only the substring (:math:`\mathrm{l1}`::math:`\mathrm{l2}`) of each element of :math:`\mathrm{ch}` is to be used in determining the sorted order.
**l2** : int
Only the substring (:math:`\mathrm{l1}`::math:`\mathrm{l2}`) of each element of :math:`\mathrm{ch}` is to be used in determining the sorted order.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the values will be sorted into ASCII order.
If :math:`\mathrm{order} = \texttt{'R'}`, into reverse ASCII order.
**Returns**
**ch** : str, ndarray, shape :math:`\left(\textit{m2}\right)`
These values are rearranged into sorted order.
.. _m01cc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{l2} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{len}\left(\mathrm{ch}[0]\right) = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l2}\leq \mathrm{len}\left(\mathrm{ch}[0]\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{l1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{l2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l1}\leq \mathrm{l2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{l1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{l2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l2}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{len}\left(\mathrm{ch}[0]\right) = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{len}\left(\mathrm{ch}[0]\right)\leq 255`.
.. _m01cc-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``charvec_sort`` is based on Singleton's implementation of the 'median-of-three' Quicksort algorithm (see Singleton (1969)), but with two additional modifications.
First, small subfiles are sorted by an insertion sort on a separate final pass (see Sedgewick (1978)) Second, if a subfile is partitioned into two very unbalanced subfiles, the larger of them is flagged for special treatment: before it is partitioned, its end points are swapped with two random points within it; this makes the worst case behaviour extremely unlikely.
Only the substring (:math:`\mathrm{l1}`::math:`\mathrm{l2}`) of each element of the array :math:`\mathrm{ch}` is used to determine the sorted order, but the entire elements are rearranged into sorted order.
.. _m01cc-py2-py-references:
**References**
Sedgewick, R, 1978, `Implementing Quicksort programs`, Comm. ACM (21), 847--857
Singleton, R C, 1969, `An efficient algorithm for sorting with minimal storage: Algorithm 347`, Comm. ACM (12), 185--187
"""
raise NotImplementedError
[docs]def realvec_rank(rv, m1, order):
r"""
``realvec_rank`` ranks a vector of `float` numbers in ascending or descending order.
.. _m01da-py2-py-doc:
For full information please refer to the NAG Library document for m01da
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01daf.html
.. _m01da-py2-py-parameters:
**Parameters**
**rv** : float, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{rv}` must contain `float` values to be ranked.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{rv}` to be ranked.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the values will be ranked in ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` contain the ranks of the corresponding elements of :math:`\mathrm{rv}`. Note that the ranks are in the range :math:`\mathrm{m1}` to :math:`\textit{m2}`: thus, if :math:`\mathrm{rv}[i-1]` is the first element in the rank order, :math:`\mathrm{irank}[i-1]` is set to :math:`\mathrm{m1}`.
.. _m01da-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01da-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``realvec_rank`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
The ranking is stable: equal elements preserve their ordering in the input data.
.. _m01da-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def intvec_rank(iv, m1, order):
r"""
``intvec_rank`` ranks a vector of integer numbers in ascending or descending order.
.. _m01db-py2-py-doc:
For full information please refer to the NAG Library document for m01db
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01dbf.html
.. _m01db-py2-py-parameters:
**Parameters**
**iv** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{iv}` must contain integer values to be ranked.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{iv}` to be ranked.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the values will be ranked in ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` contain the ranks of the corresponding elements of :math:`\mathrm{iv}`. Note that the ranks are in the range :math:`\mathrm{m1}` to :math:`\textit{m2}`: thus, if :math:`\mathrm{iv}[i-1]` is the first element in the rank order, :math:`\mathrm{irank}[i-1]` is set to :math:`\mathrm{m1}`.
.. _m01db-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01db-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``intvec_rank`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
The ranking is stable: equal elements preserve their ordering in the input data.
.. _m01db-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def charvec_rank(ch, m1, l1, l2, order):
r"""
``charvec_rank`` ranks a vector of character data in ASCII or reverse ASCII order of a specified substring.
.. _m01dc-py2-py-doc:
For full information please refer to the NAG Library document for m01dc
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01dcf.html
.. _m01dc-py2-py-parameters:
**Parameters**
**ch** : str, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{ch}` must contain character data to be ranked.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{ch}` to be ranked.
**l1** : int
Only the substring (:math:`\mathrm{l1}`::math:`\mathrm{l2}`) of each element of :math:`\mathrm{ch}` is to be used in determining the rank order.
**l2** : int
Only the substring (:math:`\mathrm{l1}`::math:`\mathrm{l2}`) of each element of :math:`\mathrm{ch}` is to be used in determining the rank order.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the values will be ranked in ASCII order.
If :math:`\mathrm{order} = \texttt{'R'}`, in reverse ASCII order.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` contain the ranks of the corresponding elements of :math:`\mathrm{ch}`. Note that the ranks are in the range :math:`\mathrm{m1}` to :math:`\textit{m2}`: thus, if :math:`\mathrm{ch}[i-1]` is the first element in the rank order, :math:`\mathrm{irank}[i-1]` is set to :math:`\mathrm{m1}`.
.. _m01dc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{l2} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{len}\left(\mathrm{ch}[0]\right) = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l2}\leq \mathrm{len}\left(\mathrm{ch}[0]\right)`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{l1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{l2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l1}\leq \mathrm{l2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{l1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{l2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{l2}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{len}\left(\mathrm{ch}[0]\right) = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{len}\left(\mathrm{ch}[0]\right)\leq 255`.
.. _m01dc-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``charvec_rank`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
The ranking is stable: equal elements preserve their ordering in the input data.
Only the substring (:math:`\mathrm{l1}`::math:`\mathrm{l2}`) of each element of the array :math:`\mathrm{ch}` is used to determine the rank order.
.. _m01dc-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def realmat_rank_rows(rm, m1, n1, order):
r"""
``realmat_rank_rows`` ranks the rows of a matrix of `float` numbers in ascending or descending order.
.. _m01de-py2-py-doc:
For full information please refer to the NAG Library document for m01de
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01def.html
.. _m01de-py2-py-parameters:
**Parameters**
**rm** : float, array-like, shape :math:`\left(\textit{m2}, \textit{n2}\right)`
Columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of rows :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{rm}` must contain `float` data to be ranked.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first row of :math:`\mathrm{rm}` to be ranked.
**n1** : int
The index of the first column of :math:`\mathrm{rm}` to be used.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the rows will be ranked in ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` contain the ranks of the corresponding rows of :math:`\mathrm{rm}`. Note that the ranks are in the range :math:`\mathrm{m1}` to :math:`\textit{m2}`: thus, if the :math:`i`\ th row of :math:`\mathrm{rm}` is the first in the rank order, :math:`\mathrm{irank}[i-1]` is set to :math:`\mathrm{m1}`.
.. _m01de-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{ldm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\leq \textit{ldm}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\leq \textit{n2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{n2}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constratint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01de-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``realmat_rank_rows`` ranks rows :math:`\mathrm{m1}` to :math:`\textit{m2}` of a matrix, using the data in columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of those rows.
The ordering is determined by first ranking the data in column :math:`\mathrm{n1}`, then ranking any tied rows according to the data in column :math:`\mathrm{n1}+1`, and so on up to column :math:`\textit{n2}`.
``realmat_rank_rows`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
The ranking is stable: equal rows preserve their ordering in the input data.
.. _m01de-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def intmat_rank_rows(im, m1, n1, order):
r"""
``intmat_rank_rows`` ranks the rows of a matrix of integer numbers in ascending or descending order.
.. _m01df-py2-py-doc:
For full information please refer to the NAG Library document for m01df
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01dff.html
.. _m01df-py2-py-parameters:
**Parameters**
**im** : int, array-like, shape :math:`\left(\textit{m2}, \textit{n2}\right)`
Columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of rows :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{im}` must contain `int` data to be ranked.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first row of :math:`\mathrm{im}` to be ranked.
**n1** : int
The index of the first column of :math:`\mathrm{im}` to be used.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the rows will be ranked in ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` contain the ranks of the corresponding rows of :math:`\mathrm{im}`. Note that the ranks are in the range :math:`\mathrm{m1}` to :math:`\textit{m2}`: thus, if the :math:`i`\ th row of :math:`\mathrm{im}` is the first in the rank order, :math:`\mathrm{irank}[i-1]` is set to :math:`\mathrm{m1}`.
.. _m01df-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{ldm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\leq \textit{ldm}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\leq \textit{n2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{n2}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01df-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``intmat_rank_rows`` ranks rows :math:`\mathrm{m1}` to :math:`\textit{m2}` of a matrix, using the data in columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of those rows.
The ordering is determined by first ranking the data in column :math:`\mathrm{n1}`, then ranking any tied rows according to the data in column :math:`\mathrm{n1}+1`, and so on up to column :math:`\textit{n2}`.
``intmat_rank_rows`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
The ranking is stable: equal rows preserve their ordering in the input data.
.. _m01df-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def realmat_rank_columns(rm, m1, n1, order):
r"""
``realmat_rank_columns`` ranks the columns of a matrix of `float` numbers in ascending or descending order.
.. _m01dj-py2-py-doc:
For full information please refer to the NAG Library document for m01dj
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01djf.html
.. _m01dj-py2-py-parameters:
**Parameters**
**rm** : float, array-like, shape :math:`\left(\textit{m2}, \textit{n2}\right)`
Rows :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of :math:`\mathrm{rm}` must contain `float` data to be ranked.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first row of :math:`\mathrm{rm}` to be used.
**n1** : int
The index of the first column of :math:`\mathrm{rm}` to be ranked.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the columns will be ranked in ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\textit{n2}\right)`
Elements :math:`\mathrm{n1}` to :math:`\textit{n2}` of :math:`\mathrm{irank}` contain the ranks of the corresponding columns of :math:`\mathrm{rm}`. Note that the ranks are in the range :math:`\mathrm{n1}` to :math:`\textit{n2}`: thus, if the :math:`i`\ th column of :math:`\mathrm{rm}` is the first in the rank order, :math:`\mathrm{irank}[i-1]` is set to :math:`\mathrm{n1}`.
.. _m01dj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{ldm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\leq \textit{ldm}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\leq \textit{n2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{n2}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01dj-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``realmat_rank_columns`` ranks columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of a matrix, using the data in rows :math:`\mathrm{m1}` to :math:`\textit{m2}` of those columns.
The ordering is determined by first ranking the data in row :math:`\mathrm{m1}`, then ranking any tied columns according to the data in row :math:`\mathrm{m1}+1`, and so on up to row :math:`\textit{m2}`.
``realmat_rank_columns`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
The ranking is stable: equal columns preserve their ordering in the input data.
.. _m01dj-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def intmat_rank_columns(im, m1, n1, order):
r"""
``intmat_rank_columns`` ranks the columns of a matrix of integer numbers in ascending or descending order.
.. _m01dk-py2-py-doc:
For full information please refer to the NAG Library document for m01dk
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01dkf.html
.. _m01dk-py2-py-parameters:
**Parameters**
**im** : int, array-like, shape :math:`\left(\textit{m2}, \textit{n2}\right)`
Rows :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of :math:`\mathrm{im}` must contain integer data to be ranked.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first row of :math:`\mathrm{im}` to be used.
**n1** : int
The index of the first column of :math:`\mathrm{im}` to be ranked.
**order** : str, length 1
If :math:`\mathrm{order} = \texttt{'A'}`, the columns will be ranked in ascending (i.e., nondecreasing) order.
If :math:`\mathrm{order} = \texttt{'D'}`, into descending order.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\textit{n2}\right)`
Elements :math:`\mathrm{n1}` to :math:`\textit{n2}` of :math:`\mathrm{irank}` contain the ranks of the corresponding columns of :math:`\mathrm{im}`. Note that the ranks are in the range :math:`\mathrm{n1}` to :math:`\textit{n2}`: thus, if the :math:`i`\ th column of :math:`\mathrm{im}` is the first in the rank order, :math:`\mathrm{irank}[i-1]` is set to :math:`\mathrm{n1}`.
.. _m01dk-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{ldm} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\leq \textit{ldm}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\leq \textit{n2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{n1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{n1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{n2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{n2}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{order}` has an illegal value: :math:`\mathrm{order} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01dk-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``intmat_rank_columns`` ranks columns :math:`\mathrm{n1}` to :math:`\textit{n2}` of a matrix, using the data in rows :math:`\mathrm{m1}` to :math:`\textit{m2}` of those columns.
The ordering is determined by first ranking the data in row :math:`\mathrm{m1}`, then ranking any tied columns according to the data in row :math:`\mathrm{m1}+1`, and so on up to row :math:`\textit{m2}`.
``intmat_rank_columns`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
The ranking is stable: equal columns preserve their ordering in the input data.
.. _m01dk-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def arbitrary_rank(compar, m1, m2, data=None):
r"""
``arbitrary_rank`` ranks arbitrary data according to a user-supplied comparison function.
.. _m01dz-py2-py-doc:
For full information please refer to the NAG Library document for m01dz
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01dzf.html
.. _m01dz-py2-py-parameters:
**Parameters**
**compar** : callable retval = compar(i, j, data=None)
:math:`\mathrm{compar}` must specify the relative ordering of any two data items; it must return :math:`\mathbf{True}` if item :math:`\mathrm{i}` must come strictly **after** item :math:`\mathrm{j}` in the rank ordering.
**Parameters**
**i** : int
:math:`\mathrm{i}` and :math:`\mathrm{j}` identify the data items to be compared.
**j** : int
:math:`\mathrm{i}` and :math:`\mathrm{j}` identify the data items to be compared.
**data** : arbitrary, optional, modifiable in place
User-communication data for callback functions.
**Returns**
**retval** : bool
Must be :math:`\mathbf{True}` if item :math:`\mathrm{i}` must come strictly **after** item :math:`\mathrm{j}` in the rank ordering.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
:math:`\mathrm{m1}` must specify the lower bound of the range of data items to be ranked, and the range of ranks to be assigned. Specifically, ``arbitrary_rank`` ranks the data items identified by integers in the range :math:`\mathrm{m1}` to :math:`\mathrm{m2}`, and assigns ranks in the range :math:`\mathrm{m1}` to :math:`\mathrm{m2}` which are stored in elements :math:`\mathrm{m1}-1` to :math:`\mathrm{m2}-1` of :math:`\mathrm{irank}`.
**m2** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
:math:`\mathrm{m2}` must specify the upper bound of the range of data items to be ranked, and the range of ranks to be assigned. Specifically, ``arbitrary_rank`` ranks the data items identified by integers in the range :math:`\mathrm{m1}` to :math:`\mathrm{m2}`, and assigns ranks in the range :math:`\mathrm{m1}` to :math:`\mathrm{m2}` which are stored in elements :math:`\mathrm{m1}-1` to :math:`\mathrm{m2}-1` of :math:`\mathrm{irank}`.
**data** : arbitrary, optional
User-communication data for callback functions.
**Returns**
**irank** : int, ndarray, shape :math:`\left(\mathrm{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\mathrm{m2}-1` of :math:`\mathrm{irank}` contain the ranks of the data items :math:`\mathrm{m1}` to :math:`\mathrm{m2}`. Note that the ranks are in the range :math:`\mathrm{m1}` to :math:`\mathrm{m2}`: thus, if item :math:`i` is first in the rank ordering, :math:`\mathrm{irank}[i-1]` contains :math:`\mathrm{m1}`.
.. _m01dz-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \mathrm{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m2}\geq 1`.
.. _m01dz-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``arbitrary_rank`` is a general purpose function for ranking arbitrary data. ``arbitrary_rank`` does not access the data directly; instead it calls :math:`\mathrm{compar}` to determine the relative ordering of any two data items.
The data items are identified simply by an integer in the range :math:`\mathrm{m1}` to :math:`\mathrm{m2}`.
``arbitrary_rank`` uses a variant of list-merging, as described on pages 165--166 in Knuth (1973).
The function takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least :math:`10`.
.. _m01dz-py2-py-references:
**References**
Knuth, D E, 1973, `The Art of Computer Programming (Volume 3)`, (2nd Edition), Addison--Wesley
"""
raise NotImplementedError
[docs]def realvec_rank_rearrange(rv, m1, irank):
r"""
``realvec_rank_rearrange`` rearranges a vector of real numbers into the order specified by a vector of ranks.
.. _m01ea-py2-py-doc:
For full information please refer to the NAG Library document for m01ea
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01eaf.html
.. _m01ea-py2-py-parameters:
**Parameters**
**rv** : float, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{rv}` must contain real values to be rearranged.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
:math:`\mathrm{m1}` and :math:`\textit{m2}` must specify the range of the ranks supplied in :math:`\mathrm{irank}` and the elements of :math:`\mathrm{rv}` to be rearranged.
**irank** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` must contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`, which are interpreted as a vector of ranks.
**Returns**
**rv** : float, ndarray, shape :math:`\left(\textit{m2}\right)`
These values are rearranged into rank order. For example, if :math:`\mathrm{irank}[i-1] = \mathrm{m1}`, then the initial value of :math:`\mathrm{rv}[i-1]` is moved to :math:`\mathrm{rv}[\mathrm{m1}-1]`.
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Used as internal workspace prior to being restored and hence is unchanged.
.. _m01ea-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}[I-1]` contains an out-of-range value: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{irank}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}` contains a repeated value: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01ea-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``realvec_rank_rearrange`` is designed to be used typically in conjunction with the ranking functions :meth:`realvec_rank`, :meth:`intvec_rank`, :meth:`charvec_rank`, :meth:`realmat_rank_rows`, :meth:`intmat_rank_rows`, :meth:`realmat_rank_columns`, :meth:`intmat_rank_columns` and :meth:`arbitrary_rank`.
After one of those functions has been called to determine a vector of ranks, ``realvec_rank_rearrange`` can be called to rearrange a vector of real numbers into the rank order.
If the vector of ranks has been generated in some other way, then :meth:`permute_check` should be called to check its validity before ``realvec_rank_rearrange`` is called.
"""
raise NotImplementedError
[docs]def intvec_rank_rearrange(iv, m1, irank):
r"""
``intvec_rank_rearrange`` rearranges a vector of integer numbers into the order specified by a vector of ranks.
.. _m01eb-py2-py-doc:
For full information please refer to the NAG Library document for m01eb
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ebf.html
.. _m01eb-py2-py-parameters:
**Parameters**
**iv** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{iv}` must contain integer values to be rearranged.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
:math:`\mathrm{m1}` and :math:`\textit{m2}` specify the range of the ranks supplied in :math:`\mathrm{irank}` and the elements of :math:`\mathrm{iv}` to be rearranged.
**irank** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` must contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`, which are interpreted as a vector of ranks.
**Returns**
**iv** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
These values are rearranged into rank order. For example, if :math:`\mathrm{irank}[i-1] = \mathrm{m1}`, then the initial value of :math:`\mathrm{iv}[i-1]` is moved to :math:`\mathrm{iv}[\mathrm{m1}-1]`.
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Used as internal workspace prior to being restored and hence is unchanged.
.. _m01eb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}[I-1]` contains an out-of-range value: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{irank}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}` contains a repeated value: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01eb-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``intvec_rank_rearrange`` is designed to be used typically in conjunction with the ranking functions :meth:`realvec_rank`, :meth:`intvec_rank`, :meth:`charvec_rank`, :meth:`realmat_rank_rows`, :meth:`intmat_rank_rows`, :meth:`realmat_rank_columns`, :meth:`intmat_rank_columns` and :meth:`arbitrary_rank`.
After one of those functions has been called to determine a vector of ranks, ``intvec_rank_rearrange`` can be called to rearrange a vector of integer numbers into the rank order.
If the vector of ranks has been generated in some other way, then :meth:`permute_check` should be called to check its validity before ``intvec_rank_rearrange`` is called.
"""
raise NotImplementedError
[docs]def charvec_rank_rearrange(ch, m1, irank):
r"""
``charvec_rank_rearrange`` rearranges a vector of character data into the order specified by a vector of ranks.
.. _m01ec-py2-py-doc:
For full information please refer to the NAG Library document for m01ec
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ecf.html
.. _m01ec-py2-py-parameters:
**Parameters**
**ch** : str, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{ch}` must contain character data to be rearranged.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The range of the ranks supplied in :math:`\mathrm{irank}` and the elements of :math:`\mathrm{ch}` to be rearranged.
**irank** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` must contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`, which are interpreted as a vector of ranks.
**Returns**
**ch** : str, ndarray, shape :math:`\left(\textit{m2}\right)`
These values are rearranged into rank order. For example, if :math:`\mathrm{irank}[i-1] = \mathrm{m1}`, then the initial value of :math:`\mathrm{ch}[i-1]` is moved to :math:`\mathrm{ch}[\mathrm{m1}-1]`.
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Used as internal workspace prior to being restored and hence is unchanged.
.. _m01ec-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
On entry, :math:`\mathrm{len}\left(\mathrm{ch}[0]\right) = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{len}\left(\mathrm{ch}[0]\right)\leq 255`.
(`errno` :math:`3`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}[I-1]` contains an out-of-range value: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{irank}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`4`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}` contains a repeated value: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01ec-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``charvec_rank_rearrange`` is designed to be used typically in conjunction with the ranking functions :meth:`realvec_rank`, :meth:`intvec_rank`, :meth:`charvec_rank`, :meth:`realmat_rank_rows`, :meth:`intmat_rank_rows`, :meth:`realmat_rank_columns`, :meth:`intmat_rank_columns` and :meth:`arbitrary_rank`.
After one of those functions has been called to determine a vector of ranks, ``charvec_rank_rearrange`` can be called to rearrange a vector of character data into the rank order.
If the vector of ranks has been generated in some other way, then :meth:`permute_check` should be called to check its validity before ``charvec_rank_rearrange`` is called.
"""
raise NotImplementedError
[docs]def cmplxvec_rank_rearrange(cv, m1, irank):
r"""
``cmplxvec_rank_rearrange`` rearranges a vector of complex numbers into the order specified by a vector of ranks.
.. _m01ed-py2-py-doc:
For full information please refer to the NAG Library document for m01ed
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01edf.html
.. _m01ed-py2-py-parameters:
**Parameters**
**cv** : complex, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{cv}` must contain complex values to be rearranged.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
:math:`\mathrm{m1}` and :math:`\textit{m2}` must specify the range of the ranks supplied in :math:`\mathrm{irank}` and the elements of :math:`\mathrm{cv}` to be rearranged.
**irank** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{irank}` must contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`, which are interpreted as a vector of ranks.
**Returns**
**cv** : complex, ndarray, shape :math:`\left(\textit{m2}\right)`
These values are rearranged into rank order. For example, if :math:`\mathrm{irank}[i-1] = \mathrm{m1}`, then the initial value of :math:`\mathrm{cv}[i-1]` is moved to :math:`\mathrm{cv}[\mathrm{m1}-1]`.
**irank** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Used as internal workspace prior to being restored and hence is unchanged.
.. _m01ed-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}[I-1]` contains an out-of-range value: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{irank}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\mathrm{irank}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{irank}` contains a repeated value: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01ed-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``cmplxvec_rank_rearrange`` is designed to be used typically in conjunction with the ranking functions :meth:`realvec_rank`, :meth:`intvec_rank`, :meth:`charvec_rank`, :meth:`realmat_rank_rows`, :meth:`intmat_rank_rows`, :meth:`realmat_rank_columns`, :meth:`intmat_rank_columns` and :meth:`arbitrary_rank`.
After one of those functions has been called to determine a vector of ranks, ``cmplxvec_rank_rearrange`` can be called to rearrange a vector of complex numbers into the rank order.
If the vector of ranks has been generated in some other way, then :meth:`permute_check` should be called to check its validity before ``cmplxvec_rank_rearrange`` is called.
"""
raise NotImplementedError
[docs]def realvec_search(valid, rv, item, m1=1):
r"""
``realvec_search`` searches an ordered vector of `float` numbers and returns the index of the first value equal to the sought-after item.
.. _m01na-py2-py-doc:
For full information please refer to the NAG Library document for m01na
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01naf.html
.. _m01na-py2-py-parameters:
**Parameters**
**valid** : bool
If :math:`\mathrm{valid}` is set to :math:`\mathbf{True}` argument checking will be performed. If :math:`\mathrm{valid}` is set to :math:`\mathbf{False}` ``realvec_search`` will be called without argument checking (which includes checking that array :math:`\mathrm{rv}` is sorted in ascending order) and the function will return with no exception or warning is raised. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01naf.html#fcomments>`__ for further details.
**rv** : float, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` contain `float` values to be searched.
**item** : float
The sought-after item.
**m1** : int, optional
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{rv}` to be searched.
**Returns**
**irv** : int
Note: this argument represents an array index; the value returned will be base-1.
The index of the first value equal to the sought-after item.
.. _m01na-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`2`)
On entry, :math:`\mathrm{rv}` must be sorted in ascending order: :math:`\mathrm{rv}\text{ element }\langle\mathit{\boldsymbol{value}}\rangle > \text{ element }\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
.. _m01na-py2-py-notes:
**Notes**
``realvec_search`` is based on Professor Niklaus Wirth's implementation of the Binary Search algorithm (see Wirth (2004)), but with two modifications.
First, if the sought-after item is less than the value of the first element of the array to be searched, :math:`-1` is returned.
Second, if a value equal to the sought-after item is not found, the index of the immediate lower value is returned.
.. _m01na-py2-py-references:
**References**
Wirth, N, 2004, `Algorithms and Data Structures`, 35--36, Prentice Hall
"""
raise NotImplementedError
[docs]def intvec_search(valid, iv, item, m1=1):
r"""
``intvec_search`` searches an ordered vector of integer numbers and returns the index of the first value equal to the sought-after item.
.. _m01nb-py2-py-doc:
For full information please refer to the NAG Library document for m01nb
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01nbf.html
.. _m01nb-py2-py-parameters:
**Parameters**
**valid** : bool
If :math:`\mathrm{valid}` is set to :math:`\mathbf{True}` argument checking will be performed. If :math:`\mathrm{valid}` is set to :math:`\mathbf{False}` ``intvec_search`` will be called without argument checking (which includes checking that array :math:`\mathrm{iv}` is sorted in ascending order) and the function will return with no exception or warning is raised. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01nbf.html#fcomments>`__ for further details.
**iv** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` contain integer values to be searched.
**item** : int
The sought-after item.
**m1** : int, optional
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{iv}` to be searched.
**Returns**
**iiv** : int
Note: this argument represents an array index; the value returned will be base-1.
The index of the first value equal to the sought-after item.
.. _m01nb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`2`)
On entry, :math:`\mathrm{iv}` must be sorted in ascending order: :math:`\mathrm{iv}\text{ element }\langle\mathit{\boldsymbol{value}}\rangle > \text{ element }\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
.. _m01nb-py2-py-notes:
**Notes**
``intvec_search`` is based on Professor Niklaus Wirth's implementation of the Binary Search algorithm (see Wirth (2004)), but with two modifications.
First, if the sought-after item is less than the value of the first element of the array to be searched, :math:`-1` is returned.
Second, if a value equal to the sought-after item is not found, the index of the immediate lower value is returned.
.. _m01nb-py2-py-references:
**References**
Wirth, N, 2004, `Algorithms and Data Structures`, 35--36, Prentice Hall
"""
raise NotImplementedError
[docs]def charvec_search(valid, ch, item, m1=1):
r"""
``charvec_search`` examines an ordered vector of strings and returns the index of the first value equal to the sought-after item.
Character items are compared according to the ASCII collating sequence.
.. _m01nc-py2-py-doc:
For full information please refer to the NAG Library document for m01nc
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ncf.html
.. _m01nc-py2-py-parameters:
**Parameters**
**valid** : bool
If :math:`\mathrm{valid}` is set to :math:`\mathbf{True}` argument checking will be performed. If :math:`\mathrm{valid}` is set to :math:`\mathbf{False}` ``charvec_search`` will be called without argument checking, which includes checking that array :math:`\mathrm{ch}` is sorted in ascending order and the function will return with no exception or warning is raised. See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ncf.html#fcomments>`__ for further details.
**ch** : str, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` contain character data to be searched.
**item** : str
The sought-after item. Trailing space characters are ignored.
**m1** : int, optional
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{ch}` to be searched.
**Returns**
**ich** : int
Note: this argument represents an array index; the value returned will be base-1.
The index of the first value equal to the sought-after item.
.. _m01nc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`2`)
On entry, :math:`\mathrm{ch}` must be sorted in ascending order: :math:`\mathrm{ch}\text{ element }\langle\mathit{\boldsymbol{value}}\rangle > \text{ element }\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq \mathrm{m1}`.
(`errno` :math:`5`)
On entry, the length of each element of :math:`\mathrm{ch}` must be at most :math:`255`: maximum string length :math:`\text{} = \langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01nc-py2-py-notes:
**Notes**
``charvec_search`` is based on Professor Niklaus Wirth's implementation of the Binary Search algorithm (see Wirth (2004)), but with two modifications.
First, if the sought-after item is less than the value of the first element of the array to be searched, :math:`-1` is returned.
Second, if a value equal to the sought-after item is not found, the index of the immediate lower value is returned.
.. _m01nc-py2-py-references:
**References**
Wirth, N, 2004, `Algorithms and Data Structures`, 35--36, Prentice Hall
"""
raise NotImplementedError
[docs]def realvec_vec_search(valid, rv, m1, m2, item, comm=None):
r"""
``realvec_vec_search`` searches a strictly ordered vector of `float` numbers and returns the indices of the largest numbers in the vector which are smaller than or equal to the sought-after items.
.. _m01nd-py2-py-doc:
For full information please refer to the NAG Library document for m01nd
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ndf.html
.. _m01nd-py2-py-parameters:
**Parameters**
**valid** : bool
If :math:`\mathrm{valid}` is set to :math:`\mathbf{True}` argument checking will be performed. If :math:`\mathrm{valid}` is set to :math:`\mathbf{False}` ``realvec_vec_search`` will be called without argument checking (which includes checking that array :math:`\mathrm{rv}` is sorted in strictly ascending order). See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ndf.html#fcomments>`__ for further details.
**rv** : float, array-like, shape :math:`\left(n\right)`
:math:`X`, the `float` values to be searched.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the first element of :math:`\mathrm{rv}` to be searched.
**m2** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The index of the last element of :math:`\mathrm{rv}` to be searched.
**item** : float, array-like, shape :math:`\left(m\right)`
:math:`Z`, the sought-after items.
**comm** : None or dict, communication object, optional, modified in place
Communication structure.
If :math:`\mathrm{comm}` is **None** then searching is performed using an offset-based binary search.
Otherwise, :math:`\mathrm{comm}` may be supplied uninitialized.
It will then be populated and the routine will perform a direct search of :math:`\mathrm{rv}`.
The populated :math:`\mathrm{comm}` can then be supplied again to subsequent calls for repeated searching of :math:`\mathrm{rv}`.
**Returns**
**idx** : int, ndarray, shape :math:`\left(m\right)`
Note: this argument represents array indices; the values returned will be base-1.
:math:`\mathrm{idx}[i-1]` contains the index of the largest entry in :math:`\mathrm{rv}` which is smaller than or equal to :math:`\mathrm{item}[i-1]`.
.. _m01nd-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`2`)
On entry, :math:`\mathrm{rv}` must be sorted in strictly ascending order: :math:`\mathrm{rv}\text{ element }\langle\mathit{\boldsymbol{value}}\rangle > \text{ element }\langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 0`.
(`errno` :math:`4`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{m2} = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \mathrm{m2}\leq n`.
(`errno` :math:`5`)
On entry, :math:`n = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`n \geq 2`.
(`errno` :math:`6`)
On entry, :math:`m = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`m \geq 1`.
(`errno` :math:`7`)
On entry, the values in :math:`\mathrm{rv}` are such that the required value of :math:`\textit{lk}` would overflow the current platform's largest positive integer value.
(`errno` :math:`8`)
:math:`\mathrm{comm}` may have become corrupted.
.. _m01nd-py2-py-notes:
**Notes**
``realvec_vec_search`` searches an array, :math:`X`, of :math:`n` strictly-increasing `float` numbers, :math:`X_i < X_{{i+1}}`, :math:`i = 1\ldots \left(n-1\right)`, for the elements of an unordered array of :math:`m` `float` numbers, :math:`Z`.
If a value equal to a sought-after item :math:`Z_i` is not found in :math:`X`, the index of the immediate lower value is returned.
If :math:`Z_i` is less than :math:`X_1`, :math:`-1` is returned.
The function implements the direct search algorithm presented as Algorithm 8 in Cannizzo (2018).
It precomputes a scalar, :math:`H`, and a reference vector of indices, :math:`K`, that it uses to speed up searches of :math:`X`.
The length of :math:`K` is a function of the number of entries in :math:`X` and their values, and the function provides a mechanism to compute what this length should be.
If the amount of memory required for :math:`K` is infeasible, ``realvec_vec_search`` implements offset-based binary search (Algorithm 5 in Cannizzo (2018)) as an alternative that does not require :math:`K` to be used.
See `Further Comments <https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01ndf.html#fcomments>`__ for more information on the relative time complexities of the two search algorithms.
.. _m01nd-py2-py-references:
**References**
Cannizzo, F, 2018, `A fast and vectorizable alternative to binary search in O(1) with wide applicability to arrays of floating point numbers`, Journal of Parallel and Distributed Computing (113), 37--54
"""
raise NotImplementedError
[docs]def permute_invert(iperm, m1):
r"""
``permute_invert`` inverts a permutation, and hence converts a rank vector to an index vector, or vice versa.
.. _m01za-py2-py-doc:
For full information please refer to the NAG Library document for m01za
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01zaf.html
.. _m01za-py2-py-parameters:
**Parameters**
**iperm** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{iperm}` must contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
:math:`\mathrm{m1}` and :math:`\textit{m2}` must specify the range of elements used in the array :math:`\mathrm{iperm}` and the range of values in the permutation, as specified under :math:`\mathrm{iperm}`.
**Returns**
**iperm** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
These elements contain the inverse permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`.
.. _m01za-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
:math:`\mathrm{iperm}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{iperm}[I-1]` contains an out-of-range value: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{iperm}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\mathrm{iperm}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{iperm}` contains a repeated value: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01za-py2-py-notes:
**Notes**
`In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.`
There are two common ways of describing a permutation using an integer vector :math:`\mathrm{iperm}`.
The first uses ranks: :math:`\mathrm{iperm}[i-1]` holds the position to which the :math:`i`\ th data element should be moved in order to sort the data; in other words its rank in the sorted order.
The second uses indices: :math:`\mathrm{iperm}[i-1]` holds the current position of the data element which would occur in :math:`i`\ th position in sorted order.
For example, given the values
.. math::
3.5\quad \text{ }\quad 5.9\quad \text{ }\quad 2.9\quad \text{ }\quad 0.5
to be sorted in ascending order, the ranks would be
.. math::
3\quad \text{ }\quad 4\quad \text{ }\quad 2\quad \text{ }\quad 1
.. math::
2\quad \text{ }\quad 3\quad \text{ }\quad 1\quad \text{ }\quad 0
and the indices would be
.. math::
4\quad \text{ }\quad 3\quad \text{ }\quad 1\quad \text{ }\quad 2
.. math::
3\quad \text{ }\quad 2\quad \text{ }\quad 0\quad \text{ }\quad 1
The functions :meth:`realvec_rank`, :meth:`intvec_rank`, :meth:`charvec_rank`, :meth:`realmat_rank_rows`, :meth:`intmat_rank_rows`, :meth:`realmat_rank_columns`, :meth:`intmat_rank_columns` and :meth:`arbitrary_rank` generate ranks, and the functions :meth:`realvec_rank_rearrange`, :meth:`intvec_rank_rearrange`, :meth:`charvec_rank_rearrange` and :meth:`cmplxvec_rank_rearrange` require ranks to be supplied to specify the reordering.
However if it is desired simply to refer to the data in sorted order without actually reordering them, indices are more convenient than ranks.
``permute_invert`` can be used to convert ranks to indices, or indices to ranks, as the two permutations are inverses of each another.
"""
raise NotImplementedError
[docs]def permute_check(iperm, m1):
r"""
``permute_check`` checks the validity of a permutation.
.. _m01zb-py2-py-doc:
For full information please refer to the NAG Library document for m01zb
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01zbf.html
.. _m01zb-py2-py-parameters:
**Parameters**
**iperm** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{iperm}` must be set to values which are supposed to be a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. If they are a valid permutation, the function exits with no exception or warning is raised.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
The range of elements used in the array :math:`\mathrm{iperm}` and the range of values in the permutation, as specified under :math:`\mathrm{iperm}`.
**Returns**
**iperm** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Used as internal workpsace prior to being restored and hence is unchanged.
.. _m01zb-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
:math:`\mathrm{iperm}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{iperm}[I-1]` contains an out-of-range value: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{iperm}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\mathrm{iperm}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{iperm}` contains a repeated value: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01zb-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``permute_check`` can be used to check the validity of user-supplied ranks or indices, without the ranks or indices being corrupted.
"""
raise NotImplementedError
[docs]def permute_decompose(iperm, m1):
r"""
``permute_decompose`` decomposes a permutation into cycles, as an aid to reordering ranked data.
.. _m01zc-py2-py-doc:
For full information please refer to the NAG Library document for m01zc
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/m01/m01zcf.html
.. _m01zc-py2-py-parameters:
**Parameters**
**iperm** : int, array-like, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{iperm}` must contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`.
**m1** : int
Note: this argument represents an array index; the value you supply must be base-1 for compatibility with the NAG Engine.
:math:`\mathrm{m1}` and :math:`\textit{m2}` must specify the range of elements used in the array :math:`\mathrm{iperm}` and the range of values in the permutation, as specified under :math:`\mathrm{iperm}`.
**Returns**
**iperm** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Is used as internal workpsace prior to being restored and hence is unchanged.
**icycl** : int, ndarray, shape :math:`\left(\textit{m2}\right)`
Elements :math:`\mathrm{m1}-1` to :math:`\textit{m2}-1` of :math:`\mathrm{icycl}` contain a representation of the permutation as a list of cycles, with the first integer in each cycle negated. (See :ref:`Notes <m01zc-py2-py-notes>`.)
.. _m01zc-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle` and :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\leq \textit{m2}`.
(`errno` :math:`1`)
On entry, :math:`\mathrm{m1} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{m1}\geq 1`.
(`errno` :math:`1`)
On entry, :math:`\textit{m2} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\textit{m2}\geq 1`.
(`errno` :math:`2`)
:math:`\mathrm{iperm}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{iperm}[I-1]` contains an out-of-range value: :math:`I = \langle\mathit{\boldsymbol{value}}\rangle`, :math:`\mathrm{iperm}[I-1] = \langle\mathit{\boldsymbol{value}}\rangle`.
(`errno` :math:`3`)
:math:`\mathrm{iperm}[\mathrm{m1}:\textit{m2}-1]` does not contain a permutation of the integers :math:`\mathrm{m1}` to :math:`\textit{m2}`. :math:`\mathrm{iperm}` contains a repeated value: :math:`\langle\mathit{\boldsymbol{value}}\rangle`.
.. _m01zc-py2-py-notes:
**Notes**
`No equivalent traditional C interface for this routine exists in the NAG Library.`
``permute_decompose`` is provided as an aid to reordering arbitrary data structures without using additional storage.
However, you should consider carefully whether it is necessary to rearrange yourr data, or whether it would be simpler and more efficient to refer to the data in sorted order using an index vector, or to create a copy of the data in sorted order.
To rearrange data into a different order without using additional storage, the simplest method is to decompose the permutation which specifies the new order into cycles and then to do a cyclic permutation of the data items in each cycle. (This is the method used by the reordering functions :meth:`realvec_rank_rearrange`, :meth:`intvec_rank_rearrange`, :meth:`charvec_rank_rearrange` and :meth:`cmplxvec_rank_rearrange`.) Given a vector IRANK which specifies the ranks of the data (as generated by the functions :meth:`realvec_rank`, :meth:`intvec_rank`, :meth:`charvec_rank`, :meth:`realmat_rank_rows`, :meth:`intmat_rank_rows`, :meth:`realmat_rank_columns`, :meth:`intmat_rank_columns` and :meth:`arbitrary_rank`), ``permute_decompose`` generates a new vector :math:`\mathrm{icycl}`, in which the permutation is represented in its component cycles, with the first element of each cycle negated.
For example, the permutation
.. math::
\begin{array}{ccc} \begin{array}{cc}5&7\end{array} & \begin{array}{cccc}4&2&1&6\end{array} & \begin{array}{c}3\end{array} \end{array}
is composed of the cycles
.. math::
\begin{array}{ccc} \begin{pmatrix}1&5\end{pmatrix} & \begin{pmatrix}2&7&3&4\end{pmatrix} & \begin{pmatrix}6\end{pmatrix} \end{array}
and the vector :math:`\mathrm{icycl}` generated by ``permute_decompose`` contains
.. math::
\begin{array}{ccccccc}-1&5&-2&7&3&4&-6\end{array}
In order to rearrange the data according to the specified ranks:
item :math:`6` must be left in place;
items :math:`1` and :math:`5` must be interchanged;
items :math:`4`, :math:`2`, :math:`7` and :math:`3` must be moved right one place round the cycle.
The complete rearrangement can be achieved by the following logic:
loop for :math:`k = \mathrm{m1}` to :math:`\textit{m2}`
set :math:`i = \mathrm{icycl}[k-1]`
if :math:`i < 0` then
set :math:`j = -i`
else
swap items :math:`i` and :math:`j`
"""
raise NotImplementedError
