0
# ND4J Parameter Server Client
1

2
ND4J Parameter Server Client is a distributed parameter server client component for ND4J (N-Dimensional Arrays for Java), enabling parameter synchronization across multiple nodes in distributed machine learning workloads. It serves as the client-side interface for communicating with parameter servers in distributed training scenarios.
3

4
## Package Information
5

6
- **Package Name**: nd4j-parameter-server-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.nd4j
10
- **Artifact ID**: nd4j-parameter-server-client
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>org.nd4j</groupId>
16
    <artifactId>nd4j-parameter-server-client</artifactId>
17
    <version>0.9.1</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.nd4j.parameterserver.client.ParameterServerClient;
25
```
26

27
## Basic Usage
28

29
```java
30
import org.nd4j.parameterserver.client.ParameterServerClient;
31
import org.nd4j.linalg.api.ndarray.INDArray;
32
import io.aeron.Aeron;
33

34
// Build a parameter server client
35
ParameterServerClient client = ParameterServerClient.builder()
36
    .aeron(aeronInstance)
37
    .ndarrayRetrieveUrl("aeron:udp?endpoint=localhost:40323")
38
    .ndarraySendUrl("aeron:udp?endpoint=localhost:40324")
39
    .subscriberHost("localhost")
40
    .masterStatusHost("localhost")
41
    .masterStatusPort(33000)
42
    .subscriberPort(40625)
43
    .subscriberStream(12)
44
    .build();
45

46
// Push model parameters to the server
47
INDArray modelParameters = model.params();
48
client.pushNDArray(modelParameters);
49
```
50

51
## Architecture
52

53
The ND4J Parameter Server Client operates within a distributed training architecture:
54

55
- **Client**: Manages parameter communication with the parameter server
56
- **Parameter Server**: Centralized component for parameter storage and aggregation
57
- **Aeron Transport**: High-performance messaging layer for low-latency communication
58
- **INDArray Integration**: Direct support for ND4J's n-dimensional array format
59

60
The client uses a builder pattern for configuration and integrates seamlessly with DeepLearning4J training workflows, particularly in distributed training scenarios using ParallelWrapper.
61

62
## Capabilities
63

64
### Parameter Server Client
65

66
Core client functionality for communicating with distributed parameter servers, supporting high-performance parameter synchronization across multiple training nodes.
67

68
```java { .api }
69
public class ParameterServerClient {
70
    public static Builder builder();
71
    public void pushNDArray(INDArray array);
72
}
73
```
74

75
### Parameter Synchronization
76

77
Sends model parameters to the parameter server for distributed training coordination.
78

79
```java { .api }
80
/**
81
 * Push an NDArray containing model parameters to the parameter server
82
 * @param array - The INDArray containing parameters to synchronize
83
 */
84
public void pushNDArray(INDArray array);
85
```
86

87
**Usage Example:**
88

89
```java
90
// After local training step, push updated parameters
91
INDArray updatedParams = neuralNetwork.params();
92
parameterServerClient.pushNDArray(updatedParams);
93
```
94

95
### Client Configuration
96

97
Builder pattern for configuring the parameter server client with network endpoints and transport settings.
98

99
```java { .api }
100
public static class Builder {
101
    /**
102
     * Set the Aeron messaging transport instance
103
     * @param aeron - Aeron instance for high-performance messaging
104
     * @return Builder instance for method chaining
105
     */
106
    public Builder aeron(Aeron aeron);
107
    
108
    /**
109
     * Set the URL for retrieving NDArrays from the parameter server
110
     * @param url - Aeron URL for parameter retrieval
111
     * @return Builder instance for method chaining
112
     */
113
    public Builder ndarrayRetrieveUrl(String url);
114
    
115
    /**
116
     * Set the URL for sending NDArrays to the parameter server
117
     * @param url - Aeron URL for parameter sending
118
     * @return Builder instance for method chaining
119
     */
120
    public Builder ndarraySendUrl(String url);
121
    
122
    /**
123
     * Set the subscriber host address
124
     * @param host - Host address for subscriber connection
125
     * @return Builder instance for method chaining
126
     */
127
    public Builder subscriberHost(String host);
128
    
129
    /**
130
     * Set the master status server host
131
     * @param host - Host address for status server
132
     * @return Builder instance for method chaining
133
     */
134
    public Builder masterStatusHost(String host);
135
    
136
    /**
137
     * Set the master status server port
138
     * @param port - Port number for status server
139
     * @return Builder instance for method chaining
140
     */
141
    public Builder masterStatusPort(int port);
142
    
143
    /**
144
     * Set the subscriber port
145
     * @param port - Port number for subscriber connection
146
     * @return Builder instance for method chaining
147
     */
148
    public Builder subscriberPort(int port);
149
    
150
    /**
151
     * Set the subscriber stream identifier
152
     * @param stream - Stream identifier for subscriber
153
     * @return Builder instance for method chaining
154
     */
155
    public Builder subscriberStream(int stream);
156
    
157
    /**
158
     * Build and return the configured ParameterServerClient
159
     * @return Configured ParameterServerClient instance
160
     */
161
    public ParameterServerClient build();
162
}
163
```
164

165
**Configuration Example:**
166

167
```java
168
ParameterServerClient client = ParameterServerClient.builder()
169
    .aeron(mediaDriver.getAeron())
170
    .ndarrayRetrieveUrl("aeron:udp?endpoint=localhost:40323")
171
    .ndarraySendUrl("aeron:udp?endpoint=localhost:40324") 
172
    .subscriberHost("localhost")
173
    .masterStatusHost("localhost")
174
    .masterStatusPort(33000)
175
    .subscriberPort(40625)
176
    .subscriberStream(12)
177
    .build();
178
```
179

180
## Types
181

182
```java { .api }
183
/**
184
 * Builder class for configuring ParameterServerClient instances
185
 */
186
public static class Builder {
187
    // Builder methods as documented above
188
}
189

190
/**
191
 * ND4J's core n-dimensional array interface for parameter data
192
 * From org.nd4j.linalg.api.ndarray package
193
 */
194
interface INDArray {
195
    // Core n-dimensional array operations
196
    // Full definition available in ND4J documentation
197
}
198

199
/**
200
 * Aeron high-performance messaging transport
201
 * From io.aeron package  
202
 */
203
class Aeron {
204
    // High-performance messaging transport implementation
205
    // Full definition available in Aeron documentation
206
}
207
```
208

209
## Integration with DeepLearning4J
210

211
The ParameterServerClient integrates with DeepLearning4J's parallel training infrastructure:
212

213
```java
214
// Used within custom trainer implementations
215
public class ParameterServerTrainer extends DefaultTrainer {
216
    private ParameterServerClient parameterServerClient;
217
    
218
    @Override
219
    public void feedDataSet(DataSet dataSet, long time) {
220
        // Perform local training
221
        model.fit(dataSet);
222
        
223
        // Synchronize parameters
224
        parameterServerClient.pushNDArray(model.params());
225
    }
226
}
227

228
// Factory for creating parameter server trainers
229
ParameterServerTrainerContext context = new ParameterServerTrainerContext();
230
ParallelWrapper wrapper = new ParallelWrapper.Builder(model)
231
    .trainerFactory(context)
232
    .workers(numWorkers)
233
    .build();
234
```
235

236
## Dependencies
237

238
The client requires these key dependencies:
239

240
- **Aeron**: High-performance messaging transport (`io.aeron:aeron-all`)
241
- **ND4J Core**: N-dimensional array library (`org.nd4j:nd4j-api`)
242
- **Parameter Server Node**: Server-side components (`org.nd4j:nd4j-parameter-server-node`)