From d933e483188b8e46021beb14d7d2c41be01f36b9 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Mon, 15 Mar 2021 21:58:07 -0500 Subject: [PATCH 01/10] add meshgrid to creation functions --- spec/API_specification/creation_functions.md | 27 ++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index a072bd968..4c3c831e4 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -289,6 +289,33 @@ Returns evenly spaced numbers over a specified interval. - a one-dimensional array containing evenly spaced values. +(function-meshgrid)= +### meshgrid(x, /, *, indexing='xy') + +Returns coordinate matrices from coordinate vectors. + +### Special cases + +- For `n` one dimensional arrays `x1, x2, ..., xn` with lengths `Ni = len(xi)`, this function returns `(N1, N2, N3, ..., Nn)` shaped arrays if the indexing is 'ij' or `(N2, N1, N3, ..., Nn)` shaped arrays if indexing 'xy'. + +- The 0-D and 1-D case, the indexing keyword has no effect. + +### Parameters + +- **x**: _<array>_ + + - One dimensional array representing the coordinates of the grid. + +- **indexing**: _Optional\[str]_ + + - Cartesian 'xy' by default or 'ij' for matrix indexing of the output. + +### Returns + +- **out**: _\[<array>\]_ + + - List of N arrays with rank N. + (function-ones)= ### ones(shape, /, *, dtype=None, device=None) From 2b630031f3f88bbf9c535a42e94796bcddd15003 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Tue, 16 Mar 2021 17:42:22 -0500 Subject: [PATCH 02/10] add review changes --- spec/API_specification/creation_functions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 4c3c831e4..09c27b441 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -290,7 +290,7 @@ Returns evenly spaced numbers over a specified interval. - a one-dimensional array containing evenly spaced values. (function-meshgrid)= -### meshgrid(x, /, *, indexing='xy') +### meshgrid(*arrays, /, *, indexing='xy') Returns coordinate matrices from coordinate vectors. @@ -302,19 +302,19 @@ Returns coordinate matrices from coordinate vectors. ### Parameters -- **x**: _<array>_ +- ***arrays**: _<array>_ - - One dimensional array representing the coordinates of the grid. + - One dimensional arrays representing the coordinates of the grid. -- **indexing**: _Optional\[str]_ +- **indexing**: _Optional\[ str ]_ - Cartesian 'xy' by default or 'ij' for matrix indexing of the output. ### Returns -- **out**: _\[<array>\]_ +- **out**: _Tuple\[ <array>, ... ]_ - - List of N arrays with rank N. + - List of N arrays with rank `max(2, N)`. (function-ones)= ### ones(shape, /, *, dtype=None, device=None) From 7ba8f4823c927502f34eb1ec0a846a2a76fd7663 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Fri, 2 Apr 2021 00:25:47 -0500 Subject: [PATCH 03/10] add notes section to meshgrid function --- spec/API_specification/creation_functions.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 09c27b441..e3ac6d7c1 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -290,7 +290,7 @@ Returns evenly spaced numbers over a specified interval. - a one-dimensional array containing evenly spaced values. (function-meshgrid)= -### meshgrid(*arrays, /, *, indexing='xy') +### meshgrid(*arrays, /, indexing='xy') Returns coordinate matrices from coordinate vectors. @@ -302,7 +302,7 @@ Returns coordinate matrices from coordinate vectors. ### Parameters -- ***arrays**: _<array>_ +- **\*arrays**: _<array>_ - One dimensional arrays representing the coordinates of the grid. @@ -316,6 +316,22 @@ Returns coordinate matrices from coordinate vectors. - List of N arrays with rank `max(2, N)`. +### Notes + +This function supports indexing conventions using the `indexing` keyword. In the case of `xy` the function will return a meshgrid with cartesian indexing, while `ij` will use matrix indexing. The difference is illustrated by the following code snippet: + +``` +xv, yv = meshgrid(x, y, indexing='xy') +for i in range(nx): + for j in range(ny): + # treat xv[j, i], yv[j, i] + +xv, yv = meshgrid(x, y, indexing='ij') +for i in range(nx): + for j in range(ny): + # treat xv[i, j], yv[i, j] +``` + (function-ones)= ### ones(shape, /, *, dtype=None, device=None) From 6d451965e18c5d56391d37b63e5b659502ea1ef9 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Tue, 13 Apr 2021 16:56:07 -0500 Subject: [PATCH 04/10] add review changes --- spec/API_specification/creation_functions.md | 42 ++++++++++---------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index e3ac6d7c1..69b9efb68 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -294,31 +294,17 @@ Returns evenly spaced numbers over a specified interval. Returns coordinate matrices from coordinate vectors. -### Special cases - -- For `n` one dimensional arrays `x1, x2, ..., xn` with lengths `Ni = len(xi)`, this function returns `(N1, N2, N3, ..., Nn)` shaped arrays if the indexing is 'ij' or `(N2, N1, N3, ..., Nn)` shaped arrays if indexing 'xy'. - -- The 0-D and 1-D case, the indexing keyword has no effect. - -### Parameters - -- **\*arrays**: _<array>_ - - - One dimensional arrays representing the coordinates of the grid. - -- **indexing**: _Optional\[ str ]_ - - - Cartesian 'xy' by default or 'ij' for matrix indexing of the output. +#### Parameters -### Returns +- **arrays**: _Sequence\[ <array> ]_ -- **out**: _Tuple\[ <array>, ... ]_ + - one-dimensional arrays representing grid coordinates. Must have a numeric data type. - - List of N arrays with rank `max(2, N)`. +- **indexing**: _str_ -### Notes + - Cartesian 'xy' or matrix 'ij' indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the `indexing` keyword has no effect and should be ignored. Default: `'xy'`. -This function supports indexing conventions using the `indexing` keyword. In the case of `xy` the function will return a meshgrid with cartesian indexing, while `ij` will use matrix indexing. The difference is illustrated by the following code snippet: + - In the case of `xy` the function will return a meshgrid with cartesian indexing, while `ij` will use matrix indexing. The difference is illustrated by the following code snippet: ``` xv, yv = meshgrid(x, y, indexing='xy') @@ -332,6 +318,22 @@ for i in range(nx): # treat xv[i, j], yv[i, j] ``` +#### Returns + +- **out**: _List \[ <array>, ... ]_ + + - List of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`, + + - if matrix indexing `ij` then each return array must have the shape `(N1, N2, N3, ..., Nn)`. + + - if Cartesian indexing `xy`, then each returned array must have shape `(N2, N1, N3, ..., Nn)`. + + - Accordingly, for the two-dimensional case with input one-dimensional arrays of length `M` and `N`, if matrix indexing `ij`, then each returned array must have shape `(M, N)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M)`. + + - Similarly, for the three-dimensional case with input one-dimensional arrays of length `M`, `N`, and `P`, if matrix indexing `ij`, then each returned array must have shape `(M, N, P)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M, P)`. + + - The returned arrays must have a numeric data type determined by {ref}`type-promotion`. + (function-ones)= ### ones(shape, /, *, dtype=None, device=None) From 4d7a5d135bc47ff56badea17f8629b3e6b6c09ff Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 19 Apr 2021 12:23:33 -0700 Subject: [PATCH 05/10] Apply suggestions from code review --- spec/API_specification/creation_functions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 69b9efb68..80f06d62d 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -320,19 +320,19 @@ for i in range(nx): #### Returns -- **out**: _List \[ <array>, ... ]_ +- **out**: _List\[ <array>, ... ]_ - - List of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`, + - List of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`, - - if matrix indexing `ij` then each return array must have the shape `(N1, N2, N3, ..., Nn)`. + - if matrix indexing `ij` then each return array must have the shape `(N1, N2, N3, ..., Nn)`. - - if Cartesian indexing `xy`, then each returned array must have shape `(N2, N1, N3, ..., Nn)`. + - if Cartesian indexing `xy`, then each returned array must have shape `(N2, N1, N3, ..., Nn)`. - - Accordingly, for the two-dimensional case with input one-dimensional arrays of length `M` and `N`, if matrix indexing `ij`, then each returned array must have shape `(M, N)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M)`. + Accordingly, for the two-dimensional case with input one-dimensional arrays of length `M` and `N`, if matrix indexing `ij`, then each returned array must have shape `(M, N)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M)`. - - Similarly, for the three-dimensional case with input one-dimensional arrays of length `M`, `N`, and `P`, if matrix indexing `ij`, then each returned array must have shape `(M, N, P)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M, P)`. + Similarly, for the three-dimensional case with input one-dimensional arrays of length `M`, `N`, and `P`, if matrix indexing `ij`, then each returned array must have shape `(M, N, P)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M, P)`. - - The returned arrays must have a numeric data type determined by {ref}`type-promotion`. + The returned arrays must have a numeric data type determined by {ref}`type-promotion`. (function-ones)= ### ones(shape, /, *, dtype=None, device=None) From 8ea1b7ac42cf6f65e2750834a3f510afd47f990f Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 19 Apr 2021 12:24:08 -0700 Subject: [PATCH 06/10] Update description --- spec/API_specification/creation_functions.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 80f06d62d..e36d6291a 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -302,21 +302,7 @@ Returns coordinate matrices from coordinate vectors. - **indexing**: _str_ - - Cartesian 'xy' or matrix 'ij' indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the `indexing` keyword has no effect and should be ignored. Default: `'xy'`. - - - In the case of `xy` the function will return a meshgrid with cartesian indexing, while `ij` will use matrix indexing. The difference is illustrated by the following code snippet: - -``` -xv, yv = meshgrid(x, y, indexing='xy') -for i in range(nx): - for j in range(ny): - # treat xv[j, i], yv[j, i] - -xv, yv = meshgrid(x, y, indexing='ij') -for i in range(nx): - for j in range(ny): - # treat xv[i, j], yv[i, j] -``` + - Cartesian 'xy' or matrix 'ij' indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the `indexing` keyword has no effect and should be ignored. Default: `'xy'`. #### Returns From 32852ef2b8cdd3ef8a6da941d0c5384e6fcb7e43 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 19 Apr 2021 12:30:41 -0700 Subject: [PATCH 07/10] Add missing comment --- spec/API_specification/creation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index e36d6291a..02db7f6d9 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -310,7 +310,7 @@ Returns coordinate matrices from coordinate vectors. - List of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`, - - if matrix indexing `ij` then each return array must have the shape `(N1, N2, N3, ..., Nn)`. + - if matrix indexing `ij`, then each return array must have the shape `(N1, N2, N3, ..., Nn)`. - if Cartesian indexing `xy`, then each returned array must have shape `(N2, N1, N3, ..., Nn)`. From 803f4b75a2b5ce6b64ed70daf6a904b5ba414cec Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 19 Apr 2021 12:31:28 -0700 Subject: [PATCH 08/10] Fix grammar --- spec/API_specification/creation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 02db7f6d9..637646579 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -310,7 +310,7 @@ Returns coordinate matrices from coordinate vectors. - List of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`, - - if matrix indexing `ij`, then each return array must have the shape `(N1, N2, N3, ..., Nn)`. + - if matrix indexing `ij`, then each returned array must have the shape `(N1, N2, N3, ..., Nn)`. - if Cartesian indexing `xy`, then each returned array must have shape `(N2, N1, N3, ..., Nn)`. From 21402132f54086534fe703bdd07554ff78c34dc1 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 19 Apr 2021 12:34:48 -0700 Subject: [PATCH 09/10] Lowercase first word --- spec/API_specification/creation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index 637646579..c559c9994 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -308,7 +308,7 @@ Returns coordinate matrices from coordinate vectors. - **out**: _List\[ <array>, ... ]_ - - List of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`, + - list of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`, - if matrix indexing `ij`, then each returned array must have the shape `(N1, N2, N3, ..., Nn)`. From 457fd0c739d5608ae6b5e9d4b7f17e5422fe7ba3 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 19 Apr 2021 12:50:15 -0700 Subject: [PATCH 10/10] Make keyword-only --- spec/API_specification/creation_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/creation_functions.md b/spec/API_specification/creation_functions.md index c559c9994..7ce12f5d9 100644 --- a/spec/API_specification/creation_functions.md +++ b/spec/API_specification/creation_functions.md @@ -290,7 +290,7 @@ Returns evenly spaced numbers over a specified interval. - a one-dimensional array containing evenly spaced values. (function-meshgrid)= -### meshgrid(*arrays, /, indexing='xy') +### meshgrid(*arrays, /, *, indexing='xy') Returns coordinate matrices from coordinate vectors.