Sedaro API Docs
API docs by Redocly

Sedaro API (4.10.17)

Download OpenAPI specification:Download

Allows for consumption of Sedaro services. Read more about Sedaro at docs.sedaro.com.

Clients

Python: sedaro

  • This package provides additional functionality on top of the auto-generated OpenAPI client. See the package docs for more information.

API Key

To access the Sedaro service via this API, you will need an API key. You can generate an API key for your account in the Sedaro Management Console. Once complete, pass the API key in all requests via the X_API_KEY HTTP header.

API keys grant full access to your account and should never be shared. If you think your API key has been compromised, you can revoke it in the Management Console.

Jupyter Notebooks

For additional examples of how to use this API for modeling and simulation, see our Mod-Sim Notebooks.

Community, Support, Discussion

If you have any issues or suggestions, please reach out:

  1. Join the Sedaro Community Slack
  2. Email us at support@sedarotech.com

Known Issues

  • Error responses are more specific than what is shown throughout the documentation. A 4xx or 5xx error will be returned in all error cases. Only a 200 status indicates success. See a given error response for additional details.

MetaModels

Introduction to Modeling in Sedaro

Sedaro uses SedaroML (Sedaro Modeling Language) to define models and systems of models. SedaroML defines system properties and structure as normalized, interrelated, and hierarchical blocks of attributes. SedaroML is JSON-based and is designed to be easily human and machine readable/writeable. This includes model interpretation, traversal, etc. Each SedaroML model class defining the structure and properties of a system is called a Metamodel.

Metamodel classes are instantiated to create instances of the system. Metamodel instances consist of a set of Blocks and attributes (described below) and can be either Agent Templates or Scenarios.

  • Agent Templates: define the model for a system.
  • Scenarios: define the instantiation of a system and the configuration of the simulation.

When a Scenario configures a simulation, it instantiates Agent Templates to create Agents. The Agents are then connected to each other to form a system of systems. This system is then simulated according to the Scenario's configuration.

To help with organization and other functionality, each instantiated Metamodel is associated with a Branch that is apart of a Repository. This allows for versioning, branching, merging, and tracking of changes to the Metamodel and the system it defines. The Metamodel is stored in the data key of the Branch JSON object.

Other key concepts

There are some specific concepts in SedaroML that are important to understand:

  • Attributes: Individual properties of a Block (e.g., mass, voltage, etc.) captured as a key-value pair.

  • Root: The root refers to the highest level key/value pairs of the JSON-object of SedaroML. The keys are attributes, just like on Blocks, but root is not a Block itself. All Metamodels contain blocks and index attributes in root which store and help with querying for all Blocks in the Metamodel.

  • Blocks: A Block is a set of attributes, including a type which defines the type of the Block (e.g., ReactionWheel, Battery, etc.). All Blocks are located under the blocks attribute of the model.

  • Hierarchy: The Blocks in a SedaroML model have hierarchy such that a Block type can extend one or more Block types (e.g., a ReactionWheel is a specialized Actuator and an Actuator is a specialized Component). The hierarchy of a model can be interpreted using the index and _supers meta attributes of a Metamodel. index provides a lookup to traverse from a Block type to its sub-Block types, ultimately down to the individual Block instances in the model. _supers provides a lookup to traverse from a Block type to its super-Block types.

  • Relationships: The model root and its Blocks can be related to one another using relationship attributes. The _relationships meta attribute provides a lookup from Block type to that type's relationships attributes.

  • Quantity Kinds: In SedaroML, an attribute that has a value and a unit is called a "Quantity". Quantities may be composed of other Quantities, called Compound Quantities. A category of Quantities that share the same unit system is called a "Quantity Kind". If a model attribute is an explicit Quantity, it will be included in the _quantityKinds meta attribute lookup. Attributes that are Explicit Quantity Kinds may be defined in any of the supported units for the Quantity Kind. For example, all angle attributes in SedaroML may be defined in either degrees or radians. If the unit isn't provided, the default unit for the given Quantity Kind is assumed.

SedaroML is used to define both Agent Templates and Scenario models, with Scenario models referencing Agent Template Branches (and therefore their models) via the templateRef attribute of an Agent Block.

Example of a mock Metamodel instance in a Branch data key, demonstrating some of the meta attributes:

{
    "type": "Spacecraft",
    "blocks": {
        "N05o9ixRguGxORKXZ_123": {
        "id": "N05o9ixRguGxORKXZ_123",
            "type": "Battery",
            "packs": ["N05oGhcT-9k9vSTAGn456"]
        },
        "N05oGhcT-9k9vSTAGn456": {
            "id": "N05oGhcT-9k9vSTAGn456",
            "type": "BatteryPack",
            "battery": "N05o9ixRguGxORKXZ_123"
        }
        "N05o79yULy9NUw1zTk789": {
        "id": "N05o79yULy9NUw1zTk789",
            "type": "ReactionWheel",
            "inertia": 0.1
        },
    },
    "index": {
        "Actuator": ["ReactionWheel"],
        "Component": ["Battery", "BatteryPack", "Actuator"],
        "Battery": ["N05o9ixRguGxORKXZ_123"],
        "BatteryPack": ["N05oGhcT-9k9vSTAGn456"],
        "ReactionWheel": ["N05o79yULy9NUw1zTk789"]
    },
    "_relationships": {
        "Battery": {
            "packs": {
                "inverse": "battery",
                "onDelete": "set-none",
                "optional": true,
                "target": "BatteryPack",
                "type": "ManySide"
            },
        },
        "BatteryPack": {
            "battery": {
                "inverse": "packs",
                "onDelete": "set-none",
                "optional": false,
                "target": "Battery",
                "type": "OneSide"
            },
        },
    },
}

Update a MetaModel

Metamodel root properties can be updated and multiple Blocks can be created, updated, and/or deleted in the same request as follows:

  • Properties on the MetaModel root are updated via the root key.
  • Blocks are created via dictionaries in the Blocks list, making sure to include all required fields, the type (name of the class), and exclude an id property.
  • Blocks are updated via dictionaries in the Blocks list, making sure to include an id property, the type (name of the class) and any fields to be updated.
  • Blocks are deleted via strings in the delete key corresponding to ids of Blocks to be deleted.
{
    // UPDATE root properties
    "root": {
        "property": "value"
    },
    "blocks": [
        // CREATE block
        {
            "property": "value",
            "type": "ClassName",
        },
        // UPDATE block
        {
            "id": "NWDjzoSSKT7yGJpZdSN9-",
            "property": "value",
            "type": "ClassName",
        },
    ],
    // DELETE blocks
    "delete": ["NWDk7l3UPDZ0AlJW2Ut0V", "NWDkZ7oToTp-W9IiutbnF"]
}
path Parameters
branchId
required
string (Branchid)
Request Body schema: application/json
Any of
required
object (SpacecraftModelRoot)

Class for the updateable fields on Spacecraft (root)

required
Array of Antenna (object) or CombinationalLogic (object) or ResistanceLoad (object) or PowerLoad (object) or MagneticHysteresisRod (object) or DataInterface (object) or InternalDataInterface (object) or LineOfSightReceiveInterface (object) or ThermalInterface (object) or PassiveLineOfSightTransmitInterface (object) or CooperativeLineOfSightTransmitInterface (object) or FixedSurface (object) or SunTrackingSurface (object) or VectorTrackingSurface (object) or DataMode (object) or UnresponsiveReactionWheelFailureMode (object) or UnresponsiveThrusterFailureMode (object) or UnresponsiveMagnetorquerFailureMode (object) or SensorFailureMode (object) or UnresponsiveSensorFailureMode (object) or PassivePointingMode (object) or ActivePointingMode (object) or MaxAlignPointingMode (object) or LockSpinPointingMode (object) or FieldOfViewArticulationMode (object) or StaticFieldOfViewArticulationMode (object) or TrackingFieldOfViewArticulationMode (object) or ScanFieldOfViewArticulationMode (object) or DataStorage (object) or FixedSchedule (object) or RelativeSchedule (object) or LaserCommModule (object) or FiniteStateMachine (object) or Routine (object) or DataType (object) or LoadState (object) or TempControllerState (object) or BatteryPack (object) or SphericalFuelTank (object) or SpherocylinderFuelTank (object) or ThermalInterfaceMaterial (object) or SurfaceMaterial (object) or ReactionWheel (object) or SolarPanel (object) or SolarCell (object) or BatteryCell (object) or Modem (object) or Subsystem (object) or ImpulsiveDeltaVAlgorithm (object) or GenericAdAlgorithm (object) or GenericOdAlgorithm (object) or TriadAlgorithm (object) or PidAlgorithm (object) or SlidingModeAlgorithm (object) or EkfAlgorithm (object) or MekfAlgorithm (object) or AveragingAlgorithm (object) or MagneticDetumblingAlgorithm (object) or StaticThrustControlAlgorithm (object) or GpsAlgorithm (object) or LogicalConfiguration (object) or CompoundCondition (object) or TimeCondition (object) or ElapsedTimeCondition (object) or SatelliteToSatelliteCondition (object) or TargetGroupToSatelliteCondition (object) or SameTargetMultiCondition (object) or SatelliteToScalarCondition (object) or TargetGroupToScalarCondition (object) or TargetToScalarCondition (object) or ComponentToScalarCondition (object) or SatelliteToTargetCondition (object) or TargetGroupToTargetCondition (object) or TargetToTargetCondition (object) or TargetGroupInFovCondition (object) or VectorInFovCondition (object) or TargetInFovCondition (object) or BodyInFovCondition (object) or StateTransition (object) or TargetGroup (object) or Cooler (object) or Heater (object) or Thruster (object) or Magnetorquer (object) or StaticAttitudeInitializer (object) or TriadAttitudeInitializer (object) or DirectMeasurementAttitudeInitializer (object) or FiniteDifferenceOrbitInitializer (object) or FuelReservoir (object) or Sensor (object) or OpticalAttitudeSensor (object) or TargetAttitudeSensor (object) or TargetRangeSensor (object) or TargetRangeRateSensor (object) or DirectionSensor (object) or PositionSensor (object) or TargetPositionSensor (object) or VectorSensor (object) or AngularVelocitySensor (object) or MemsAngularVelocitySensor (object) or PowerProcessor (object) or PhotovoltaicPowerProcessor (object) or SingleConvHybridPowerProcessor (object) or QuasiRegDetPowerProcessor (object) or FullyRegDetPowerProcessor (object) or SingleConvMpptPowerProcessor (object) or TwoConvMpptPowerProcessor (object) or BusRegulator (object) or BodyFrameVector (object) or LocalVector (object) or CelestialVector (object) or TargetGroupVector (object) or TargetVector (object) or OrbitalAttitudeDynamics (object) or IdealOrbitalAttitudeDynamics (object) or PropagatedOrbitKinematics (object) or SpkEphemeris (object) or StkEphemeris (object) or DataBus (object) or AreaTarget (object) or GroundTarget (object) or SpaceTarget (object) or CelestialTarget (object) or PermanentDipoleMagnet (object) or Component (object) or DynamicallyLoadedComponent (object) or ThermalDesignLayout (object) or CircularFieldOfView (object) or RectangularFieldOfView (object) or SolarArray (object) or Battery (object) (Blocks)
delete
required
Array of strings (Delete)

Responses

Request samples

Content type
application/json
Example
{
  • "root": {
    },
  • "blocks": [
    ],
  • "delete": [
    ]
}

Response samples

Content type
application/json
{
  • "crud": {
    },
  • "branch": {
    }
}

Jobs

Get all simulations

branchId is the ID of the Scenario Branch for which to get all the Simulation Jobs. If the latest query param is included, only the most recent Simulation Job is included in the list.

path Parameters
branchId
required
string (Branchid)
query Parameters
latest
string (Latest)
Value: ""

Responses

Response samples

Content type
application/json
Example
[ ]

Start a simulation

branchId is the ID of the Scenario Branch to simulate.

path Parameters
branchId
required
string (Branchid)
query Parameters
seed
integer (Seed)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "PENDING",
  • "bedRef": "string",
  • "dataArray": "string",
  • "seed": 0,
  • "simIndex": 0,
  • "overrideID": "string",
  • "snapshotIDs": {
    },
  • "scenarioHash": "string",
  • "startTime": 0,
  • "stopTime": 0,
  • "realTime": false,
  • "progress": { }
}

Get a simulation

branchId is the ID of the Scenario Branch simulated by the Simulation Job with ID jobId.

path Parameters
branchId
required
string (Branchid)
jobId
required
string (Jobid)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "PENDING",
  • "bedRef": "string",
  • "dataArray": "string",
  • "seed": 0,
  • "simIndex": 0,
  • "overrideID": "string",
  • "snapshotIDs": {
    },
  • "scenarioHash": "string",
  • "startTime": 0,
  • "stopTime": 0,
  • "realTime": false,
  • "progress": { }
}

Terminate a simulation

branchId is the ID of the Scenario Branch simulated by the Simulation Job with ID jobId.

path Parameters
branchId
required
string (Branchid)
jobId
required
string (Jobid)

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get all studies

branchId is the ID of the Scenario Template Branch for which to get all the Study Jobs. If the latest query param is included, only the most recent Study Job is included in the list.

path Parameters
branchId
required
string (Branchid)
query Parameters
latest
string (Latest)
Value: ""

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Start a study

branchId is the ID of the Scenario Template Branch to simulate.

path Parameters
branchId
required
string (Branchid)
query Parameters
iterations
integer (Iterations)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "PENDING",
  • "scenarioHash": "string",
  • "overrideID": "string"
}

Get a study

branchId is the ID of the Scenario Template Branch simulated by the Simulation Job with ID jobId.

path Parameters
branchId
required
string (Branchid)
jobId
required
string (Jobid)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "PENDING",
  • "scenarioHash": "string",
  • "overrideID": "string"
}

Terminate a study

branchId is the ID of the Scenario Template Branch simulated by the Simulation Job with ID jobId.

path Parameters
branchId
required
string (Branchid)
jobId
required
string (Jobid)

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Data

Queries

As of December 2023, Sedaro's data service has been overhauled. Different parameters are now required for requests. If your simulation was run before this time, you will continue to use the old interface (see below).

The data service now returns data in pages, instead of all at once. Data for a sim, within the given query parameters, is progressively added to a page until it is full. At that point, the page is sent to the client and the server begins assembling the next page. This continues until all data for the query has been fetched and paginated.

Downsampling has also been reworked. Instead of specifying an arbitrary number of bins, or an arbitrary bin width, data is now available for egress at fixed resolutions, following the powers of 2. Therefore, data can be downloaded at full resolution, at 1/2 resolution, at 1/4 resolution, and so on. This is achieved by including, respectively, every frame, every second frame, every fourth frame, and so forth. This way, unlike in the previous downsampling scheme, more data points will be presented where the data is dense, and fewer data points will be presented where the data is sparse.

The desired downsample level, or 'rank', are specified by the sampleRate parameter. The value of sampleRate corresponds to the denominator of the corresponding downsample level. For instance, to request data at 1/8 resolution, set a sampleRate resolution of 8. To request data at full resolution, set sampleRate to 1.

Here is an example, looking at the first 40 frames of a data series. '#' indicates a frame included in the series of a given rank. '_' indicates a frame not included in that rank.

1   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
2   # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _ # _
4   # _ _ _ # _ _ _ # _ _ _ # _ _ _ # _ _ _ # _ _ _ # _ _ _ # _ _ _ # _ _ _ # _ _ _
8   # _ _ _ _ _ _ _ # _ _ _ _ _ _ _ # _ _ _ _ _ _ _ # _ _ _ _ _ _ _ # _ _ _ _ _ _ _ 
16  # _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ # _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ # _ _ _ _ _ _ _
32  # _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ # _ _ _ _ _ _ _

A separate query is made for each page. Each returned page contains a 'continuation token' in its body. Inside the response content, this continuation token can be found at response['meta']['continuationToken']. Pass this value as the continuationToken for the next page you request. Continue doing so until an empty token is returned. At that point, there is no more data to return, and further page requests should not be made.

In all requests, either a sampleRate or a continuation token must be provided. It is not necessary to specify a sampleRate when a request includes a continuation token.

New interface:

  • id: The ID of the data set to query. This ID is defined on a Simulation Job.

  • start: The start time of the window in MJD. If omitted, defaults to the minimum timestamp in the dataset.

  • stop: The stop time of the window in MJD. If omitted, defaults to the maximum timestamp in the dataset.

  • streams: (optional) The specific agents and engines for which to fetch data. If omitted, all streams are fetched. This argument takes the form of a list of requests separated by commas. A request can have either one or two elements. The first element is always the ID of the Agent (str). The second element (optional) is the name of an engine (str). This must be one of the following: 'GNC', 'CDH', 'Power', 'Thermal'. If the second element is not provided, all data from all engines of the given Agent are fetched. If a request has two elements, they are separated by a period. Here is an example:

    ...&streams=NT06aqHUT5djI1_JPAsck.CDH,NT06aqHUT5djI1_JPAsck.Power,NT0Ln1gS8elWEK4Y-l7m-

    This will fetch the Power and CDH data for Agent(id='NT06aqHUT5djI1_JPAsck'), and all data for Agent(id='NT0Ln1gS8elWEK4Y-l7m-').

  • shape (optional): Specifies whether the data should be nested or flat. Options: FLAT (default) and NESTED. Examples: Flat: {'a.b': [1, 2, 3], 'a.c': [4, 5, 6]} Nested: {'a': {'b': [1, 2, 3], 'c': [4, 5, 6]}}

  • axisOrder: (optional) The shape of each series in the response. Options: TIME_MINOR (default) and TIME_MAJOR. NOTE: unlike the old Data Service in which the default was TIME_MAJOR, the default in the new Data Service is TIME_MINOR. Examples: Data at time 1: [1, 2] Data at time 2: [3, 4] Data at time 3: [5, 6] TIME_MINOR: [[1, 3, 5], [2, 4, 6]] TIME_MAJOR: [[1, 2], [3, 4], [5, 6]]

  • binWidth: (optional, temporarily disabled) The bin width to use to down-sample the data. If omitted, data will be full resolution.

  • sampleRate: (optional) The downsampling rank to use. 1 for full resolution, 2 for half resolution, 4 for 1/4 resolution, and so on. Must be an integer power of 2. Required if no continuationToken is provided.

  • 'continuationToken' (optional) Required if no sampleRate is provided. Retrieved from the previously fetched page, as described above.

  • 'encoding' (optional) The encoding in which to receive data. Currently accepted values are json and msgpack. Default: json.

    Note: Timestamps of individual data points are left-inclusive and right-exclusive. For example, if start is 2 and stop is 5, and there are timestamps at 1, 3, and 5, all three data points will be included, not just the data points at 1 and 3. This is because the data point at timestamp 1 is valid for the time range [1, 3) and part of this time range is included in the query.

For simulation runs performed before the release and deployment of Data Service v3 in December 2023, continue to use the following interface:

  • id: The ID of the data set to query. This ID is defined on a Simulation Job.

  • start: The start time of the window in MJD. If omitted, defaults to the minimum timestamp in the dataset.

  • stop: The stop time of the window in MJD. If omitted, defaults to the maximum timestamp in the dataset.

  • binWidth: (optional) The bin width to use to down-sample the data. If omitted, data will be full resolution.

  • axisOrder: (optional) The shape of each series in the response. Options: TIME_MAJOR (default) and TIME_MINOR.

  • streams: (optional) The specific agents and engines for which to fetch data. If omitted, all streams are fetched. This argument, if provided, follows the same syntax specified above for the streams parameter in the new interface.

    Example request: GET: /data/<id>?start=<start>&stop=<stop>&binWidth=<binWidth>

Response

Data is returned from a query in the following format:

{
    "series": {
        <streamId>: [
            [<timestamp1::MJD>, <timestamp2::MJD>, ...],
            {
                <agentId>: {
                    <blockId>: {
                        <stateVariableA>: [<valueA1>, <valueA2>, ...],
                        <stateVariableB>: [<valueB1>, <valueB2>, ...],
                        ...
                    },
                    <stateVariableC>: [<valueC1>, <valueC2>, ...]
                },
                ...
            }
        ],
        ...
    }
}

Note that a "Stream" is a set of state variables that share the same timestamps. Specifically, the values in a Stream correspond to a modsim Engine of a particular Agent. The series object contains a key for each stream in the data set. The value of each stream key is a 2-element array. The first element is an array of timestamps - the X-axis for all variables in the stream. The second element is an object containing the state variables that compose the stream. The state variables are grouped under an Agent ID and then a Block ID (if applicable). The value of each entry is an array of values that aligns with the timestamp vector.

Axis Order (axisOrder)

Axis order defines the shape of each multi-dimensional series in the Data Service query response. In the following example, n is the time dimension, position is a notional State Variable of shape (3,), and matrix is a notional State Variable of shape (3, 4).

TIME_MAJOR

  • position.shape == (n, 3)
  • matrix.shape == (n, 3, 4)

TIME_MINOR

  • position.shape == (3, n)
  • matrix.shape == (3, 4, n)

Ephemerides

The Data Service also includes an endpoint for bulk fetching of ephemerides. The following parameters are exposed: start (required): the start of the time range within which to fetch ephemerides, in MJD. stop (required): the end of the time range within which to fetch ephemerides, in MJD. resolution: the spacing at which to fetch ephemerides. For instance, if resolution is 0.1, then data will be fetched at start time, start + 0.1, start + 0.2, etc, up until the stop time is reached. bodies: the celestial bodies for which to fetch ephemerides. Supported bodies are SUN, MERCURY, VENUS, EARTH, MOON, MARS, JUPITER, SATURN, URANUS, NEPTUNE, and PLUTO. If this parameter is not provided, all supported bodies are included. axisOrder: TIME_MAJOR or TIME_MINOR, as above. Defaults to TIME_MINOR if not specified.

Like the data API, the ephemerides API uses paging to handle large ephemerides requests. If your request is for more than 100,000 data points, it will be broken up into pages of 100,000 data points at a time. In this case, a continuation token will be provided along with the page data. To get the next page, instead of using the parameters above, simply pass back the value of response['continuationToken'] as the argument to the continuationToken parameter, and repeat until the value the value of response.meta.continuationToken as the argument to the continuationToken parameter, and repeat until the value of response.meta.continuationToken is a null object.

Response

Data is returned from a query in the following format:

{
    "meta": {"continuationToken" : null | <token (str)>},
    "series": [
        [<timestamp1::MJD>, <timestamp2::MJD>, ...],
        {
            <celestialBodyID>: [<values>],
            <celestialBodyID>: [<values>],
            ...
        }
    ]
}

Query Data

Queries Data Service data set with ID id.

path Parameters
id
required
string (Id)
query Parameters
start
number (Start)
stop
number (Stop)
binWidth
number (Binwidth)
streams
string (Streams)

Responses

Response samples

Content type
application/json
{
  • "Data": {
    }
}

Repositories

Create new repository

Creates a new repository based on the body params. The new repository will begin with a default branch.

Request Body schema: application/json
name
required
string (Name) <= 64 characters
description
string (Description) <= 1000 characters
workspace
required
string (Workspace)
dataType
required
string (Datatype)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "workspace": "string",
  • "dataType": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "workspace": { },
  • "dataType": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "branches": [
    ]
}

Get repository

Gets a repository with id of given repoId.

path Parameters
repositoryId
required
string (Repositoryid)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "workspace": { },
  • "dataType": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "branches": [
    ]
}

Delete repository

Deletes a repository with id of given repoId and all associated branches.

path Parameters
repositoryId
required
string (Repositoryid)

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "deletedEntities": [
    ]
}

Update repository

Updates a repository with id of given repoId based on the body params.

path Parameters
repositoryId
required
string (Repositoryid)
Request Body schema: application/json
name
required
string (Name) <= 64 characters
description
string (Description) <= 1000 characters
dataType
required
string (Datatype)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "dataType": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "workspace": { },
  • "dataType": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "branches": [
    ]
}

Import branch as new repository

Imports the branch(es) from the uploaded zip file into the workspace associated with workspace id from the body. All branches will be in their own repo and given new ids. For info on exporting, see the branches export route.

Request Body schema: application/json
workspace
required
string (Workspace)
file
required
string <binary> (File)

Responses

Request samples

Content type
application/json
{
  • "workspace": "string",
  • "file": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Branches

Get a branch

Retrieves the branch with the provided id.

path Parameters
branchId
required
string (Branchid)

Responses

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "description": "string",
  • "id": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "repository": { },
  • "data": {
    }
}

Branch off existing branch

Creates a new branch based on and in the same repository as the branch associated with the provided id.

path Parameters
branchId
required
string (Branchid)
Request Body schema: application/json
name
required
string (Name) <= 32 characters
description
string (Description) <= 300 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "description": "string",
  • "id": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "repository": { },
  • "data": {
    }
}

Delete a branch

Deletes the branch with the provided id.

path Parameters
branchId
required
string (Branchid)

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "deletedEntities": [
    ]
}

Update a branch

Updates updateable fields on the branch with the provided id. Note:

  • shareable indicates whether shareable links are valid for this branch.
  • password indicates whether the shareable link requires a password.
path Parameters
branchId
required
string (Branchid)
Request Body schema: application/json
name
string (Name) <= 32 characters
description
string (Description) <= 300 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "description": "string",
  • "id": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "repository": { },
  • "data": {
    }
}

Verify branch password

Route to verify password when a user tries to access a branch with the provided id via a password protected shareable link. If successful, returns a success message with a set-cookie. The cookie stores a jwt that allows for non-owner collaborators to send GET requests to the corresponding branch.

path Parameters
branchId
required
string (Branchid)
Request Body schema: application/json
password
required
string (Password)

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Commit changes to a branch

Takes all changes to the blocks on the branch with the provided id and commits them to the corresponding version-controlled branch.

path Parameters
branchId
required
string (Branchid)
query Parameters
commitMessage
required
string (Commitmessage)

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Merge branch into another branch

Merges branch with incomingBranchId into branch with currentBranchId. This route has two functions:

  • To initiate the merge, send the request with no body. If there are no conflicts, it will successfully complete the merge and send back the resulting branch.
  • If there are conflicts, the response body will have a key of conflicts with a list of conflict objects outlining the "current" and "incoming" changes. Review the list, and send a second request to the same route including a list of resulutions (see optional resultions param in the request body schema below) indicating where you would like to keep the "current" or "incoming" changes. The indices in the resultions list should correspond with the indices of the conflicts list.
path Parameters
currentBranchId
required
string (Currentbranchid)
incomingBranchId
required
string (Incomingbranchid)
Request Body schema: application/json
resolutions
Array of strings (Resolutions)
Items Enum: "current" "incoming"

Responses

Request samples

Content type
application/json
{
  • "resolutions": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "description": "string",
  • "id": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateModified": "2019-08-24T14:15:22Z",
  • "repository": { },
  • "data": {
    }
}

Get saved branch data

Retrieves all committed branch data (object with all the blocks) from the branch with the given id.

path Parameters
branchId
required
string (Branchid)

Responses

Response samples

Content type
application/json
Example
{
  • "blocks": { },
  • "index": {
    },
  • "migrated": "string",
  • "position": {
    },
  • "velocity": [
    ],
  • "attitude": {
    },
  • "angularVelocity": {
    },
  • "angularAcceleration": [
    ],
  • "selfId": "string",
  • "cadFileName": "",
  • "cadKey": "string",
  • "cadSignedUrl": "string",
  • "cadScaleFactor": 99999999,
  • "mass": 0,
  • "inertia": [
    ],
  • "dynamicMass": 0,
  • "dynamicInertia": [
    ],
  • "torque": [
    ],
  • "activeRoutines": [ ],
  • "enabledModules": [
    ],
  • "timeStepConstraints": {
    },
  • "missionOrbit": "string",
  • "pointingModesMainRoutine": "string",
  • "activePointingMode": "string",
  • "powerProcessor": "string",
  • "dynamicCenterOfMass": [
    ],
  • "srpTorque": [
    ],
  • "dragTorque": [
    ],
  • "gravityGradientTorque": [
    ],
  • "positionSolution": [
    ],
  • "positionSolutionError": [
    ],
  • "velocitySolution": [
    ],
  • "velocitySolutionError": [
    ],
  • "definitivePositionSolution": [
    ],
  • "definitivePositionSolutionError": [
    ],
  • "definitiveVelocitySolution": [
    ],
  • "definitiveVelocitySolutionError": [
    ],
  • "predictivePositionSolution": [
    ],
  • "predictivePositionSolutionError": [
    ],
  • "predictiveVelocitySolution": [
    ],
  • "predictiveVelocitySolutionError": [
    ],
  • "attitudeSolution": [
    ],
  • "attitudeSolutionError": [
    ],
  • "attitudeSolutionErrorAngle": {
    },
  • "angularVelocitySolution": [
    ],
  • "angularVelocitySolutionError": [
    ],
  • "definitiveAttitudeSolution": [
    ],
  • "definitiveAttitudeSolutionError": [
    ],
  • "definitiveAttitudeSolutionErrorAngle": {
    },
  • "definitiveAngularVelocitySolution": [
    ],
  • "definitiveAngularVelocitySolutionError": [
    ],
  • "predictiveAttitudeSolution": [
    ],
  • "predictiveAttitudeSolutionError": [
    ],
  • "predictiveAttitudeSolutionErrorAngle": {
    },
  • "predictiveAngularVelocitySolution": [
    ],
  • "predictiveAngularVelocitySolutionError": [
    ],
  • "estimatedMagneticFieldVector": [
    ],
  • "commandedAttitude": [
    ],
  • "commandedAngularRates": [
    ],
  • "pointingErrorAngle": {
    },
  • "lvlhAxes": [
    ],
  • "enuAxes": [
    ],
  • "beta": 0,
  • "orbitalElements": {
    },
  • "shadow": true,
  • "activeCommInterfaces": [ ],
  • "type": "Spacecraft"
}

Get committed branch data

Retrieves all saved branch data (object with all the blocks) from the branch with the given id.

path Parameters
branchId
required
string (Branchid)

Responses

Response samples

Content type
application/json
Example
{
  • "blocks": { },
  • "index": {
    },
  • "migrated": "string",
  • "position": {
    },
  • "velocity": [
    ],
  • "attitude": {
    },
  • "angularVelocity": {
    },
  • "angularAcceleration": [
    ],
  • "selfId": "string",
  • "cadFileName": "",
  • "cadKey": "string",
  • "cadSignedUrl": "string",
  • "cadScaleFactor": 99999999,
  • "mass": 0,
  • "inertia": [
    ],
  • "dynamicMass": 0,
  • "dynamicInertia": [
    ],
  • "torque": [
    ],
  • "activeRoutines": [ ],
  • "enabledModules": [
    ],
  • "timeStepConstraints": {
    },
  • "missionOrbit": "string",
  • "pointingModesMainRoutine": "string",
  • "activePointingMode": "string",
  • "powerProcessor": "string",
  • "dynamicCenterOfMass": [
    ],
  • "srpTorque": [
    ],
  • "dragTorque": [
    ],
  • "gravityGradientTorque": [
    ],
  • "positionSolution": [
    ],
  • "positionSolutionError": [
    ],
  • "velocitySolution": [
    ],
  • "velocitySolutionError": [
    ],
  • "definitivePositionSolution": [
    ],
  • "definitivePositionSolutionError": [
    ],
  • "definitiveVelocitySolution": [
    ],
  • "definitiveVelocitySolutionError": [
    ],
  • "predictivePositionSolution": [
    ],
  • "predictivePositionSolutionError": [
    ],
  • "predictiveVelocitySolution": [
    ],
  • "predictiveVelocitySolutionError": [
    ],
  • "attitudeSolution": [
    ],
  • "attitudeSolutionError": [
    ],
  • "attitudeSolutionErrorAngle": {
    },
  • "angularVelocitySolution": [
    ],
  • "angularVelocitySolutionError": [
    ],
  • "definitiveAttitudeSolution": [
    ],
  • "definitiveAttitudeSolutionError": [
    ],
  • "definitiveAttitudeSolutionErrorAngle": {
    },
  • "definitiveAngularVelocitySolution": [
    ],
  • "definitiveAngularVelocitySolutionError": [
    ],
  • "predictiveAttitudeSolution": [
    ],
  • "predictiveAttitudeSolutionError": [
    ],
  • "predictiveAttitudeSolutionErrorAngle": {
    },
  • "predictiveAngularVelocitySolution": [
    ],
  • "predictiveAngularVelocitySolutionError": [
    ],
  • "estimatedMagneticFieldVector": [
    ],
  • "commandedAttitude": [
    ],
  • "commandedAngularRates": [
    ],
  • "pointingErrorAngle": {
    },
  • "lvlhAxes": [
    ],
  • "enuAxes": [
    ],
  • "beta": 0,
  • "orbitalElements": {
    },
  • "shadow": true,
  • "activeCommInterfaces": [ ],
  • "type": "Spacecraft"
}

Get branch changes

Retrieves the state of the saved branch data and committed branch data with the given id and returns them for comparison.

path Parameters
branchId
required
string (Branchid)

Responses

Response samples

Content type
application/json
{
  • "edited": {
    },
  • "committed": {
    }
}

Export branch

Exports the branch with id of given branchId. If the branch is a Scenario, also exports all branches referenced in the Scenario's agents. The returned FileResponse contains exported branch(es) as a json file(s) zipped in a directory. For info on importing, see the repositories import route.

path Parameters
branchId
required
string (Branchid)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Externals

Introduction

"Cosimulation" refers to multiple simulators working in conjunction to simulate something. Cosimulation in Sedaro is achieved via the definition of ExternalState Blocks within a Scenario model. ExternalState Blocks are related to one or more Agent Blocks in the Scenario model and they define the external cosimulation interfaces. Interfaces can be uni- or bi-directional and support two different modes: Per-Round and Spontaneous.

Cosimulation Modes

In Per-Round cosimulation, the external simulator is expected to produce and/or consume state at each "round" or simulation Engine time-step. In Spontaneous cosimulation, the external simulator may produce and/or consume state at any time. This method of cosimulation is recommended for real-time simulations (ClockConfig.realTime == true) and is important for use-cases such as commanding a system or part of a system to a new state (i.e., human/software-in-the-loop).

Spontaneous state is timestamped and interpreted such that it impacts the simulation during the round at or immediately following the timestamp. Spontaneous state production is also unique in that it is not required to ever provide a value and can remain optionally unused during a simulation. In this case, the simulation will continue to consume the initial value for the state until a new value is provided.

Each cosimulation interface is independent meaning some may be Per Round while others are Spontaneous. This also means that individual cosimulators can consume/produce state simulataneously over different interfaces.

Blocking vs Non-Blocking

Per-Round

If simulation state depends on produced external state, the simulation will block (or wait) until this state is provided via the following PATCH endpoint. Once provided, the simulation will continue until it is blocked again. Anything that is not dependent on the external state will continue to run during the blocking period.

Spontaneous

Spontaneous external state will never block the simulation but will take effect upon arrival.

Consume

Calling consume with a time value that the simulation hasn't reached yet will block until the simulation catches up. This is currently subject to a 10 minute timeout. If the request fails after 10 minutes, it is recommended that it be reattempted.

Similarly, calling consume with a time that too far lags the current simulation might result in an error as the value has been garbage collected from the simulation caches and is no longer available for retrieval. If this is the case, please fetch the data from the Data Service (via the Results API) instead.

Numpy Array Serialization/Deserialization

Because all requests and responses of this API must be JSON serializable, numpy arrays are represented in the following way in both API requests and responses (as a representation of the value np.array([x, y, z])):

{
    "ndarray": [x, y, z]
}

Configuring Cosimulation

Cosimulation interfaces are configured via the definition of ExternalState Blocks on the Scenario model before the simulation is started. The currently supported Blocks are PerRoundExternalState and SpontaneousExternalState.

See the MetaModels section for details on defining Blocks and their individual attributes.

Example Blocks:

// Per Round External State Block
{
    "id": "NZ2SGPWRnmdJhwUT4GD5k",
    "type": "PerRoundExternalState",
    "produced": [{"root": "velocity"}], // Implicit QuantityKind
    "consumed": [{"prev.root.position.as": "Position.eci"}], // Explicit QuantityKind
    "engineIndex": 0, // 0: GNC, 1: C&DH, 2: Power, 3: Thermal
    "agents": ["NSghFfVT8ieam0ydeZGX-"]
}

// Spontaneous External State Block
{
    "id": "NZ2SHUkS95z1GtmMZ0CTk",
    "type": "SpontaneousExternalState",
    "produced": [{"root": "activeOpMode"}],
    "consumed": [{"prev.root.position.as": "Position.eci"}],
    "engineIndex": 0, // 0: GNC, 1: C&DH, 2: Power, 3: Thermal
    "agents": ["NSghFfVT8ieam0ydeZGX-"]
}

Once the simulation is running, the following endpoints are used to interact with any cosimulation interfaces.

Read `ExternalState` for a simulation

This endpoint is used to read/consume state from a running simulation.

  • jobId: The ID of the running simulation for which to communicate
  • agentId: The ID of the Agent in the simulation for which the produced state pertains
  • externalStateBlockId: The ID of the relevant ExternalState Block of the Agent with ID agentId which defines the consumed state variables.
  • time (optional): The simulation time at which to read the consumed state. During SpontaneousExternalState transactions, if time is omitted, the relevant Engine's time will be used. time should be omitted for PerRoundExternalState transactions.
path Parameters
jobId
required
string (Jobid)
agentId
required
string (Agentid)
externalStateBlockId
required
string (Externalstateblockid)
query Parameters
time
number (Time)

Responses

Response samples

Content type
application/json
[
  • null
]

Set `ExternalState` for a simulation

This endpoint is used to publish/produce state to a running simulation.

  • jobId: The ID of the running simulation for which to communicate
  • agentId: The ID of the Agent in the simulation for which the produced state pertains
  • externalStateBlockId: The ID of the relevant ExternalState Block of the Agent with ID agentId which defines the produced state variables.

See details on the request body below.

path Parameters
jobId
required
string (Jobid)
agentId
required
string (Agentid)
externalStateBlockId
required
string (Externalstateblockid)
Request Body schema: application/json
values
Array of any (External State Values)
Default: []

A list containing the values of the external state to be produced. The shape of this list and its contents should match that defined by the produced query on the ExternalState block targeted by this request.

Examples:

block = {
  produced: [
    {'root': 'velocity'},
  ],
  ...
}
values == [
    [1, 0, 0]
]

block = {
  produced: [
    {'root': 'velocity'},
    {'root': 'commandedAttitude'},
  ],
  ...
}
values == [
    [1, 0, 0],
    [0, 0, 0, 1]
]

block = {
  produced: [
    {'root': 'velocity'},
    {'Battery': 'voltage'},
    # Recall that this syntax queries for the `voltage` of all blocks of type `Battery` in the model.
    # In this example, assume there is a single Battery
  ],
  ...
}
values == [
    [1, 0, 0],
    [28.2]
]

Some state must be produced as numpy arrays. In this case, follow the numpy serialization/deserialization approach described above.

timestamp
number (External State Values Timestamp [MJD])

The timestamp of the external state values. values take effect once the relevant simulation Engine's time is >= timestamp. When a timestamp is provided, all future timestamps must be sequential and increasing. When multiple timestamped values exist in a queue, the most current for which time is >= timestamp is taken.

During SpontaneousExternalState transactions, if timestamp is omitted, the relevant Engine's time will be used. timestamp should be omitted for PerRoundExternalState transactions.

Responses

Request samples

Content type
application/json
{
  • "values": [ ],
  • "timestamp": 0
}

Response samples

Content type
application/json
[
  • null
]