issue.md

We’re considering changing the object shape for a simulator declaration (declaration.js in Sergey’s examples). Right now it looks like this:

const path = require('path');

module.exports = {
  users: [{
    username: 'user1',
    userData: [
      // Data here...
    ],
  }, {
    username: 'user2',
    userData: [
      // Data here...
    ],
  }],
  computationPath: path.resolve(
    __dirname,
    'path/to/decentralized-computation.js'
  ),
  verbose: true,
};

We’re considering changing this structure to make algorithm development easier for authors. Proposition for declarations:

module.exports = {
  computationPath: './relative/path/to/computation.js',
  local: [{
    x: [/* ... */],
    y: [/* ... */],
  }, {
    x: [/* ... */],
    y: [/* ... */],
  }, {
    // And so on...
  }],
  remote: {
    // Remote variables/config here
  },
};

Key changes:

• Change computationPath to not rely on path resolution. coinstac-simulator can own this complexity.
• Change users to local and server (not shown above) to remote. This makes the declaration structure mirror the decentralized computation structure, which should make coinstac-simulator use easier for authors.
• local no longer has objects with username and userData. This strategy works well for small data sets, but it seems tedious for large collections of files or programmitic use. Instead, the local array contains objects which will become “local” runners, or clients. These objects may contain arbitrary data; coinstac-simulator can generate usernames and the necessary client setup.

In addition to object changes, we expect algorithm authors to have sets of files stored meaningfully in directories. Instead of teaching authors to use Node.js to read the files' contents, we will provide utilities:

loadFiles(pattern, filter): load files' contents into a declaration

• pattern (string): File path globbing pattern
• filter (Function): File filterer

Use

This assumes files important to an algorithm are stored in a directory:

$ tree .
└── mydir
    ├── file-1.txt
    ├── file-2.txt
    ├── file-3.txt
    └── mysubdir
        └── file-4.txt

const coinstacSimulator = require('coinstac-simulator');

module.exports = {
  local: [
    // Load all the txt files using globbing:
    coinstacSimulator.loadFiles('./path/to/files/**/*.txt'),

    // Load all files, then filter by files starting with 'M':
    coinstacSimulator.loadFiles(
      './pick/some/files/**/*',
      file => file.charAt(0) === 'M'
    ),
  ],
  remote: {
    // ...
  },
};

loadDir(path, filter)**: load a directory's contents

• path (string): File path to directory
• filter (Function): File filterer

Use

This expects the specified path to contain a subdirectories that coorespond to separate clients. Consider:

$ tree path/to/files
├── set-1
│   ├── file-1.txt
│   ├── file-2.txt
│   ├── file-3.txt
├── set-2
│   ├── file-4.txt
│   ├── file-5.txt
│   ├── file-6.txt
└── set-3
    ├── file-7.txt
    ├── file-8.txt
    └── file-9.txt

There are three local “clients” in this case: set-1, set-2, and set-3.

const coinstacSimulator = require('coinstac-simulator');

module.exports = {
  // Load the entire directory
  local: coinstacSimulator.loadDir('./path/to/files'),
  remote: {
    // ...
  },
};