# Value Federates

Value Federates provide the API for direct data transfer interfaces This includes Publications and Inputs.
Publications are outgoing data, and inputs are incoming data.
Value federates provide the API to generate and interact with those types of interfaces.
This can be done with configuration files or through API calls.

## API calls

Publications and Inputs can be declared through ValueFederate methods.
These are defined in ValueFederate.hpp and Publications.hpp and Inputs.hpp.
For the ValueFederate api the register calls return a Publication or Input reference.
These objects can be used through ValueFederate calls or as independent object with their own methods.

<!-- TODO:: add links to other generated documents -->

### File configuration

File based configuration looks primarily at an "publications" or "subscriptions" JSON array.

```json
//this should be a valid json file (except comments are not recognized in standard JSON)
{
  //example json configuration file for a value federate all arguments are optional
  "name": "valueFed", // the name of the federate
  //possible flags
  "observer": false, // indicator that the federate does not send anything
  "rollback": false, // indicator that the federate can use rollback -NOTE: not used at present
  "only_update_on_change": false, //indicator that the federate should only indicate updated values on change
  "only_transmit_on_change": false, //indicator that the federate should only publish if the value changed
  "source_only": false, //indicator that the federate is only a source and is not expected to receive anything
  "uninterruptible": false, //indicator that the federate should only return requested times
  "coretype": "test", //the type of the core "test","zmq","udp","ipc","tcp","mpi"
  "corename": "the name of the core", //this matters most for ipc and test cores, can be empty
  "coreinit": "--autobroker", // the initialization string for the core in the form of a command line arguments
  "max_iterations": 10, //the maximum number of iterations for a time step
  "period": 1.0, //the period with which federate may return time
  "offset": 0.0, // the offset shift in the period
  "time_delta": 0.0, // the minimum time between subsequent return times
  "output_delay": 0, //the propagation delay for federates to send data
  "input_delay": 0, //the input delay for external data to propagate to federates

  //Publications used in the federate
  "publications": [
    {
      "key": "pub1", // the name of the publication
      "type": "double", // the type associated with a publication (optional)
      "unit": "m", // the units associated with a publication (optional)
      "global": true, //set to true to make the key global (default is false in which case the publication is prepended with the federate name)
      "info": "this is an information string for use by the application"
    },
    {
      "key": "pub2", // the name of the publication
      "type": "double" // the type associated with a publication (optional)
      //no global:true implies this will have the federate name prepended like valueFed/pub2
    }
  ],
  //subscriptions used in the federate
  "subscriptions": [
    {
      "key": "pub1", // the key of the publication
      "required": true //set to true to make helics issue a warning if the publication is not found
    },
    {
      "key": "fedName/pub2", // the name of the publication to subscribe to
      "shortcut": "pubshortcut", //a naming shortcut for the publication for later retrieval
      "info": "this is an information string for use by the application"
    }
  ],

  "inputs": [
    { "key": "ipt2", "type": "double", "required": true, "target": "pub1" }
    //specify an input with a target multiple targets could be specified like "targets":["pub1","pub2","pub3"]
  ],

  "globals": [
    ["global1", "this is a global1 value"],
    ["global2", "this is another global value"]
  ]
}
```

### Notes

Shortcuts just provide a shortcut name for later reference instead of having to use a potentially longer key, the shortcut is only relevant inside a single federate.
