1 /*
2 * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
3 * University Research and Technology
4 * Corporation. All rights reserved.
5 * Copyright (c) 2004-2005 The University of Tennessee and The University
6 * of Tennessee Research Foundation. All rights
7 * reserved.
8 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9 * University of Stuttgart. All rights reserved.
10 * Copyright (c) 2004-2005 The Regents of the University of California.
11 * All rights reserved.
12 * Copyright (c) 2015 Los Alamos National Security, LLC. All rights
13 * reserved.
14 * $COPYRIGHT$
15 *
16 * Additional copyrights may follow
17 *
18 * $HEADER$
19 *
20 *
21 * This file is almost a complete re-write for Open MPI compared to the
22 * original mpiJava package. Its license and copyright are listed below.
23 * See <path to ompi/mpi/java/README> for more information.
24 *
25 *
26 * Licensed under the Apache License, Version 2.0 (the "License");
27 * you may not use this file except in compliance with the License.
28 * You may obtain a copy of the License at
29 *
30 * http://www.apache.org/licenses/LICENSE-2.0
31 *
32 * Unless required by applicable law or agreed to in writing, software
33 * distributed under the License is distributed on an "AS IS" BASIS,
34 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
35 * See the License for the specific language governing permissions and
36 * limitations under the License.
37 *
38 *
39 * File : Cartcomm.java
40 * Author : Xinying Li
41 * Created : Thu Apr 9 12:22:15 1998
42 * Revision : $Revision: 1.7 $
43 * Updated : $Date: 2001/10/22 21:07:55 $
44 * Copyright: Northeast Parallel Architectures Center
45 * at Syracuse University 1998
46 */
47
48 package mpi;
49
50 /**
51 * Communicator with cartesian structure.
52 */
53 public final class CartComm extends Intracomm
54 {
55 static
56 {
57 init();
58 }
59
60 private static native void init();
61
62 protected CartComm(long handle) throws MPIException
63 {
64 super(handle);
65 }
66
67 protected CartComm(long[] commRequest)
68 {
69 super(commRequest);
70 }
71
72 /**
73 * Duplicates this communicator.
74 * <p>Java binding of {@code MPI_COMM_DUP}.
75 * <p>It is recommended to use {@link #dup} instead of {@link #clone}
76 * because the last can't throw an {@link mpi.MPIException}.
77 * @return copy of this communicator
78 */
79 @Override public CartComm clone()
80 {
81 try
82 {
83 return dup();
84 }
85 catch(MPIException e)
86 {
87 throw new RuntimeException(e.getMessage());
88 }
89 }
90
91 /**
92 * Duplicates this communicator.
93 * <p>Java binding of {@code MPI_COMM_DUP}.
94 * @return copy of this communicator
95 * @throws MPIException Signals that an MPI exception of some sort has occurred.
96 */
97 @Override public CartComm dup() throws MPIException
98 {
99 MPI.check();
100 return new CartComm(dup(handle));
101 }
102
103 /**
104 * Duplicates this communicator.
105 * <p>Java binding of {@code MPI_COMM_IDUP}.
106 * <p>The new communicator can't be used before the operation completes.
107 * The request object must be obtained calling {@link #getRequest}.
108 * @return copy of this communicator
109 * @throws MPIException Signals that an MPI exception of some sort has occurred. Signals that an MPI exception of some sort has occurred.
110 */
111 @Override public CartComm iDup() throws MPIException
112 {
113 MPI.check();
114 return new CartComm(iDup(handle));
115 }
116
117 /**
118 * Duplicates this communicator with the info object used in the call.
119 * <p>Java binding of {@code MPI_COMM_DUP_WITH_INFO}.
120 * @param info info object to associate with the new communicator
121 * @return copy of this communicator
122 * @throws MPIException Signals that an MPI exception of some sort has occurred.
123 */
124 @Override public CartComm dupWithInfo(Info info) throws MPIException
125 {
126 MPI.check();
127 return new CartComm(dupWithInfo(handle, info.handle));
128 }
129
130 /**
131 * Returns cartesian topology information.
132 * <p>Java binding of the MPI operations {@code MPI_CARTDIM_GET} and
133 * {@code MPI_CART_GET}.
134 * <p>The number of dimensions can be obtained from the size of (eg)
135 * {@code dims} field of the returned object.
136 * @return object containing dimensions, periods and local coordinates
137 * @throws MPIException Signals that an MPI exception of some sort has occurred.
138 */
139 public CartParms getTopo() throws MPIException
140 {
141 MPI.check();
142 return getTopo(handle);
143 }
144
145 private native CartParms getTopo(long comm) throws MPIException;
146
147 /**
148 * Translate logical process coordinates to process rank.
149 * <p>Java binding of the MPI operation {@code MPI_CART_RANK}.
150 * @param coords Cartesian coordinates of a process
151 * @return rank of the specified process
152 * @throws MPIException Signals that an MPI exception of some sort has occurred.
153 */
154 public int getRank(int[] coords) throws MPIException
155 {
156 MPI.check();
157 return getRank(handle, coords);
158 }
159
160 private native int getRank(long comm, int[] coords) throws MPIException;
161
162 /**
163 * Translate process rank to logical process coordinates.
164 * <p>Java binding of the MPI operation {@code MPI_CART_COORDS}.
165 * @param rank rank of a process
166 * @return Cartesian coordinates of the specified process
167 * @throws MPIException Signals that an MPI exception of some sort has occurred.
168 */
169 public int[] getCoords(int rank) throws MPIException
170 {
171 MPI.check();
172 return getCoords(handle, rank);
173 }
174
175 private native int[] getCoords(long comm, int rank) throws MPIException;
176
177 /**
178 * Compute source and destination ranks for "shift" communication.
179 * <p>Java binding of the MPI operation {@code MPI_CART_SHIFT}.
180 * @param direction coordinate dimension of shift
181 * @param disp displacement
182 * @return object containing ranks of source and destination processes
183 * @throws MPIException Signals that an MPI exception of some sort has occurred.
184 */
185 public ShiftParms shift(int direction, int disp) throws MPIException
186 {
187 MPI.check();
188 return shift(handle, direction, disp);
189 }
190
191 private native ShiftParms shift(long comm, int direction, int disp)
192 throws MPIException;
193
194 /**
195 * Partition cartesian communicator into subgroups of lower dimension.
196 * <p>Java binding of the MPI operation {@code MPI_CART_SUB}.
197 * @param remainDims by dimension, {@code true} if dimension is to be kept,
198 * {@code false} otherwise
199 * @return communicator containing subgrid including this process
200 * @throws MPIException Signals that an MPI exception of some sort has occurred.
201 */
202 public CartComm sub(boolean[] remainDims) throws MPIException
203 {
204 MPI.check();
205 return new CartComm(sub(handle, remainDims));
206 }
207
208 private native long sub(long comm, boolean[] remainDims) throws MPIException;
209
210 /**
211 * Compute an optimal placement.
212 * <p>Java binding of the MPI operation {@code MPI_CART_MAP}.
213 * <p>The number of dimensions is taken to be size of the {@code dims} argument.
214 * @param dims the number of processes in each dimension
215 * @param periods {@code true} if grid is periodic,
216 * {@code false} if not, in each dimension
217 * @return reordered rank of calling process
218 * @throws MPIException Signals that an MPI exception of some sort has occurred.
219 */
220 public int map(int[] dims, boolean[] periods) throws MPIException
221 {
222 MPI.check();
223 return map(handle, dims, periods);
224 }
225
226 private native int map(long comm, int[] dims, boolean[] periods)
227 throws MPIException;
228
229 /**
230 * Select a balanced distribution of processes per coordinate direction.
231 * <p>Java binding of the MPI operation {@code MPI_DIMS_CREATE}.
232 * @param nnodes number of nodes in a grid
233 * @param dims array specifying the number of nodes in each dimension
234 * @throws MPIException Signals that an MPI exception of some sort has occurred.
235 */
236 public static void createDims(int nnodes, int[] dims) throws MPIException
237 {
238 MPI.check();
239 createDims_jni(nnodes, dims);
240 }
241
242 private static native void createDims_jni(int nnodes, int[] dims)
243 throws MPIException;
244
245 } // Cartcomm