Mondaic
PricingAbout UsDocumentation
Mondaic
Version:
No results found.

SalvusCompute API Documentation

Release: 2024.1.2

SalvusCompute is steered by input files. These can be either TOML files or equivalent JSON files. Both are shown here. Navigate to the corresponding group on the right hand side. Note that we recommend using SalvusFlow to generate the input files but you can also do it manually, of course.

Example file with all the options. Please note that many of these might be mutally exclusive and/or optional. A detailed description of all parameters follows.

Copy
[adjoint]
    forward_meta_json_filename = "meta-json.json"
    [adjoint.point_source_block]
        filename = "sources.h5"
        groups = ["sources_1", "sources_2"]
    [[adjoint.point_source]]
        location = [0.0, 1.0]
        spatial_type = "scalar"
        spatial_weights = [1.0]
        [adjoint.point_source.rotation_on_input]
            matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
        [adjoint.point_source.source_time_function]
            wavelet = "custom"
            filename = "source.h5"
            dataset_name = "/stf"
    [adjoint.gradient]
        parameterization = "rho-vp-vs"
        output_filename = "gradient.h5"
        format = "hdf5"
[domain]
    dimension = 3
    polynomial_order = 4
    [domain.mesh]
        filename = "mesh.h5"
        format = "hdf5"
    [domain.model]
        filename = "model.h5"
        format = "hdf5"
    [domain.geometry]
        filename = "geometry.h5"
        format = "hdf5"
[hardware]
    gpu = false
[output]
    memory_per_rank_in_MB = 1000.0
    [output.meta_data]
        meta_json_filename = "meta.json"
        progress_json_filename = "salvus_progress.json"
    [output.point_data]
        filename = "receivers.h5"
        format = "asdf"
        sampling_interval_in_time_steps = 10
        [[output.point_data.receiver]]
            location = "XXX"
            network_code = "AB"
            station_code = "0000"
            location_code = ""
            fields = ["displacement", "gradient-of-displacement"]
            [output.point_data.receiver.rotation_on_output]
                matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
                components = ["Z", "N", "E"]
    [output.surface_data]
        filename = "boundary_output.h5"
        format = "hdf5"
        fields = ["displacement", "strain"]
        sampling_interval_in_time_steps = 10
        side_sets = ["x0", "y0", "z0"]
        start_time_in_seconds = "0.0"
        end_time_in_seconds = "1.0"
    [output.volume_data]
        filename = "volume_output.h5"
        format = "hdf5"
        fields = ["u", "grad_u"]
        sampling_interval_in_time_steps = "10"
        start_time_in_seconds = "0.0"
        end_time_in_seconds = "1.0"
    [output.frequency_domain]
        filename = "frequency_domain.h5"
        format = "hdf5"
        fields = ["phi", "displacement"]
        frequencies = [1.0, 2.0]
        start_time_in_seconds = -0.12
        end_time_in_seconds = 1234.56
    [output.final_time_data]
        filename = "final_time_values.h5"
        format = "hdf5"
        fields = ["phi", "displacement"]
[physics]
    [physics.wave_equation]
        time_stepping_scheme = "newmark"
        start_time_in_seconds = -0.12
        end_time_in_seconds = 1234.56
        time_step_in_seconds = 0.01
        reference_time_in_seconds = 1000.0
        courant_number = 0.6
        attenuation = false
        point_source_chunk_size = 1000
        point_source_buffer_memory_in_MB_per_rank = 1000.0
        [physics.wave_equation.point_source_block]
            filename = "sources.h5"
            groups = ["sources_1", "sources_2"]
        [[physics.wave_equation.point_source]]
            location = [0.0, 1.0]
            spatial_type = "scalar"
            spatial_weights = [1.0]
            [physics.wave_equation.point_source.rotation_on_input]
                matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
            [physics.wave_equation.point_source.source_time_function]
                wavelet = "ricker"
                center_frequency = 1.0
                time_shift_in_seconds = 1.0
        [[physics.wave_equation.boundaries]]
            type = "homogeneous-dirichlet"
            side_sets = ["y0", "x1"]
            components = "XXX"
        [[physics.wave_equation.boundaries]]
            type = "ocean-loading"
            side_sets = ["y0", "x1"]
        [[physics.wave_equation.boundaries]]
            type = "absorbing"
            side_sets = ["x0", "x1", "y1"]
            width_in_meters = 1.06
            taper_amplitude = 1.07
            side_sets_are_axis_aligned = "true"
    [physics.diffusion_equation]
        time_stepping_scheme = "euler"
        start_time_in_seconds = -0.12
        end_time_in_seconds = 1234.56
        time_step_in_seconds = 0.01
        courant_number = 0.6
        [physics.diffusion_equation.initial_values]
            filename = "model.h5"
            format = "hdf5"
            field = "VP"
        [physics.diffusion_equation.final_values]
            filename = "final.h5"
    [physics.poisson_equation]
        [physics.poisson_equation.right_hand_side]
            filename = "model.h5"
            format = "hdf5"
            field = "values"
            fields = ["field1", "field2"]
        [physics.poisson_equation.initial_values]
            filename = "model.h5"
            format = "hdf5"
            field = "VP"
            fields = ["field1", "field2"]
        [[physics.poisson_equation.boundaries]]
            type = "homogeneous-dirichlet"
            side_sets = ["y0", "x1"]
            components = "XXX"
        [[physics.poisson_equation.boundaries]]
            type = "neumann"
            side_sets = ["y0", "x1"]
        [physics.poisson_equation.solution]
            filename = "solution.h5"
            fields = ["solution", "residuals"]
[solver]
    type = "cg"
    preconditioner = true
    max_iterations = 10
    relative_tolerance = 1e-06
    absolute_tolerance = 1.0
    monitor = true
{
  "adjoint": {
    "forward_meta_json_filename": "meta-json.json",
    "point_source_block": {
      "filename": "sources.h5",
      "groups": [
        "sources_1",
        "sources_2"
      ]
    },
    "point_source": [
      {
        "location": [
          0.0,
          1.0
        ],
        "spatial_type": "scalar",
        "spatial_weights": [
          1.0
        ],
        "rotation_on_input": {
          "matrix": [
            [
              1,
              0,
              0
            ],
            [
              0,
              1,
              0
            ],
            [
              0,
              0,
              1
            ]
          ]
        },
        "source_time_function": {
          "wavelet": "custom",
          "filename": "source.h5",
          "dataset_name": "/stf"
        }
      }
    ],
    "gradient": {
      "parameterization": "rho-vp-vs",
      "output_filename": "gradient.h5",
      "format": "hdf5"
    }
  },
  "domain": {
    "dimension": 3,
    "polynomial_order": 4,
    "mesh": {
      "filename": "mesh.h5",
      "format": "hdf5"
    },
    "model": {
      "filename": "model.h5",
      "format": "hdf5"
    },
    "geometry": {
      "filename": "geometry.h5",
      "format": "hdf5"
    }
  },
  "hardware": {
    "gpu": false
  },
  "output": {
    "memory_per_rank_in_MB": 1000.0,
    "meta_data": {
      "meta_json_filename": "meta.json",
      "progress_json_filename": "salvus_progress.json"
    },
    "point_data": {
      "filename": "receivers.h5",
      "format": "asdf",
      "sampling_interval_in_time_steps": 10,
      "receiver": [
        {
          "location": "XXX",
          "network_code": "AB",
          "station_code": "0000",
          "location_code": "",
          "fields": [
            "displacement",
            "gradient-of-displacement"
          ],
          "rotation_on_output": {
            "matrix": [
              [
                1,
                0,
                0
              ],
              [
                0,
                1,
                0
              ],
              [
                0,
                0,
                1
              ]
            ],
            "components": [
              "Z",
              "N",
              "E"
            ]
          }
        }
      ]
    },
    "surface_data": {
      "filename": "boundary_output.h5",
      "format": "hdf5",
      "fields": [
        "displacement",
        "strain"
      ],
      "sampling_interval_in_time_steps": 10,
      "side_sets": [
        "x0",
        "y0",
        "z0"
      ],
      "start_time_in_seconds": "0.0",
      "end_time_in_seconds": "1.0"
    },
    "volume_data": {
      "filename": "volume_output.h5",
      "format": "hdf5",
      "fields": [
        "u",
        "grad_u"
      ],
      "sampling_interval_in_time_steps": "10",
      "start_time_in_seconds": "0.0",
      "end_time_in_seconds": "1.0"
    },
    "frequency_domain": {
      "filename": "frequency_domain.h5",
      "format": "hdf5",
      "fields": [
        "phi",
        "displacement"
      ],
      "frequencies": [
        1.0,
        2.0
      ],
      "start_time_in_seconds": -0.12,
      "end_time_in_seconds": 1234.56
    },
    "final_time_data": {
      "filename": "final_time_values.h5",
      "format": "hdf5",
      "fields": [
        "phi",
        "displacement"
      ]
    }
  },
  "physics": {
    "wave_equation": {
      "time_stepping_scheme": "newmark",
      "start_time_in_seconds": -0.12,
      "end_time_in_seconds": 1234.56,
      "time_step_in_seconds": 0.01,
      "reference_time_in_seconds": 1000.0,
      "courant_number": 0.6,
      "attenuation": false,
      "point_source_chunk_size": 1000,
      "point_source_buffer_memory_in_MB_per_rank": 1000.0,
      "point_source_block": {
        "filename": "sources.h5",
        "groups": [
          "sources_1",
          "sources_2"
        ]
      },
      "point_source": [
        {
          "location": [
            0.0,
            1.0
          ],
          "spatial_type": "scalar",
          "spatial_weights": [
            1.0
          ],
          "rotation_on_input": {
            "matrix": [
              [
                1,
                0,
                0
              ],
              [
                0,
                1,
                0
              ],
              [
                0,
                0,
                1
              ]
            ]
          },
          "source_time_function": {
            "wavelet": "ricker",
            "center_frequency": 1.0,
            "time_shift_in_seconds": 1.0
          }
        }
      ],
      "boundaries": [
        [
          {
            "type": "homogeneous-dirichlet",
            "side_sets": [
              "y0",
              "x1"
            ],
            "components": "XXX"
          },
          {
            "type": "ocean-loading",
            "side_sets": [
              "y0",
              "x1"
            ]
          },
          {
            "type": "absorbing",
            "side_sets": [
              "x0",
              "x1",
              "y1"
            ],
            "width_in_meters": 1.06,
            "taper_amplitude": 1.07,
            "side_sets_are_axis_aligned": "true"
          }
        ]
      ]
    },
    "diffusion_equation": {
      "time_stepping_scheme": "euler",
      "start_time_in_seconds": -0.12,
      "end_time_in_seconds": 1234.56,
      "time_step_in_seconds": 0.01,
      "courant_number": 0.6,
      "initial_values": {
        "filename": "model.h5",
        "format": "hdf5",
        "field": "VP"
      },
      "final_values": {
        "filename": "final.h5"
      }
    },
    "poisson_equation": {
      "right_hand_side": {
        "filename": "model.h5",
        "format": "hdf5",
        "field": "values",
        "fields": [
          "field1",
          "field2"
        ]
      },
      "initial_values": {
        "filename": "model.h5",
        "format": "hdf5",
        "field": "VP",
        "fields": [
          "field1",
          "field2"
        ]
      },
      "boundaries": [
        [
          {
            "type": "homogeneous-dirichlet",
            "side_sets": [
              "y0",
              "x1"
            ],
            "components": "XXX"
          },
          {
            "type": "neumann",
            "side_sets": [
              "y0",
              "x1"
            ]
          }
        ]
      ],
      "solution": {
        "filename": "solution.h5",
        "fields": [
          "solution",
          "residuals"
        ]
      }
    }
  },
  "solver": {
    "type": "cg",
    "preconditioner": true,
    "max_iterations": 10,
    "relative_tolerance": 1e-06,
    "absolute_tolerance": 1.0,
    "monitor": true
  }
}

Adjoint group [adjoint]

If this group is present with its required members, Salvus will solve the adjoint-state problem for the specified physics and domain.

Required: False

Full example (Please note that some options might be mutally exclusive):

[adjoint]
    forward_meta_json_filename = "meta-json.json"
    [adjoint.point_source_block]
        filename = "sources.h5"
        groups = ["sources_1", "sources_2"]
    [[adjoint.point_source]]
        location = [0.0, 1.0]
        spatial_type = "scalar"
        spatial_weights = [1.0]
        [adjoint.point_source.rotation_on_input]
            matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
        [adjoint.point_source.source_time_function]
            wavelet = "custom"
            filename = "source.h5"
            dataset_name = "/stf"
    [adjoint.gradient]
        parameterization = "rho-vp-vs"
        output_filename = "gradient.h5"
        format = "hdf5"
{
  "adjoint": {
    "forward_meta_json_filename": "meta-json.json",
    "point_source_block": {
      "filename": "sources.h5",
      "groups": [
        "sources_1",
        "sources_2"
      ]
    },
    "point_source": [
      {
        "location": [
          0.0,
          1.0
        ],
        "spatial_type": "scalar",
        "spatial_weights": [
          1.0
        ],
        "rotation_on_input": {
          "matrix": [
            [
              1,
              0,
              0
            ],
            [
              0,
              1,
              0
            ],
            [
              0,
              0,
              1
            ]
          ]
        },
        "source_time_function": {
          "wavelet": "custom",
          "filename": "source.h5",
          "dataset_name": "/stf"
        }
      }
    ],
    "gradient": {
      "parameterization": "rho-vp-vs",
      "output_filename": "gradient.h5",
      "format": "hdf5"
    }
  }
}

Detailed description of all parameters:

  • forward_meta_json_filename

    • Pretty name: Forward meta json

    • Description: The json file describing the forward run

    • Parameter type: string

    • Required: True

Block of point sources. subgroup [adjoint.point_source_block]

Reads all source characteristics from a group in an HDF5 file.

Required: False

Full example (Please note that some options might be mutally exclusive):

[adjoint.point_source_block]
    filename = "sources.h5"
    groups = ["sources_1", "sources_2"]
{
  "point_source_block": {
    "filename": "sources.h5",
    "groups": [
      "sources_1",
      "sources_2"
    ]
  }
}

Detailed description of all parameters:

  • filename

    • Pretty name: Filename

    • Description: Filename containing sources

    • Parameter type: string

    • Required: True

  • groups

    • Pretty name: Groups

    • Description: Array of groups in the HDF5 file containing source information

    • Parameter type: array of strings

    • Required: True

Point source subgroup [adjoint.point_source]

Point sources for the wave equation.

Required: False

Full example (Please note that some options might be mutally exclusive):

[[adjoint.point_source]]
    location = [0.0, 1.0]
    spatial_type = "scalar"
    spatial_weights = [1.0]
    [adjoint.point_source.rotation_on_input]
        matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
    [adjoint.point_source.source_time_function]
        wavelet = "custom"
        filename = "source.h5"
        dataset_name = "/stf"
{
  "point_source": {
    "location": [
      0.0,
      1.0
    ],
    "spatial_type": "scalar",
    "spatial_weights": [
      1.0
    ],
    "rotation_on_input": {
      "matrix": [
        [
          1,
          0,
          0
        ],
        [
          0,
          1,
          0
        ],
        [
          0,
          0,
          1
        ]
      ]
    },
    "source_time_function": {
      "wavelet": "custom",
      "filename": "source.h5",
      "dataset_name": "/stf"
    }
  }
}

Detailed description of all parameters:

  • location

    • Pretty name: Source location

    • Description: The source location in Cartesian coordinates.

    • Parameter type: array of numbers

    • Required: False

  • spatial_type

    • Pretty name: Spatial type of the source

    • Description: The spatial type of the point source.

    • Parameter type: string

    • Required: False

    • Possible values: "scalar", "vector", "moment_tensor", "scalar_gradient", "vector_gradient"

  • spatial_weights

    • Pretty name: Spatial weights of the source

    • Description: The spatial weights and scale of the point source.

    • Parameter type: array of numbers

    • Required: False

subgroup [adjoint.point_source.rotation_on_input]

Optionally rotate the output. The specified rotation matrix will be applied to the final output of the receiver. It should thus rotate from Cartesian X,Y,Z to the coordinate system of your choice.

Required: False

Full example (Please note that some options might be mutally exclusive):

[adjoint.point_source.rotation_on_input]
    matrix = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
{
  "rotation_on_input": {
    "matrix": [
      [
        1,
        0,
        0
      ],
      [
        0,
        1,
        0
      ],
      [
        0,
        0,
        1
      ]
    ]
  }
}

Detailed description of all parameters:

  • matrix

    • Pretty name: Rotation Matrix

    • Description: A 2x2 or 3x3 rotation matrix.

    • Parameter type: array of arrays

    • Required: True

Source time function subgroup [adjoint.point_source.source_time_function]

The temporal evolution of the source.

Required: False

Full example (Please note that some options might be mutally exclusive):

[adjoint.point_source.source_time_function]
    wavelet = "custom"
    filename = "source.h5"
    dataset_name = "/stf"
{
  "source_time_function": {
    "wavelet": "custom",
    "filename": "source.h5",
    "dataset_name": "/stf"
  }
}

Detailed description of all parameters:

  • wavelet

    • Pretty name: Source time function

    • Description: The type of the source time function

    • Parameter type: string

    • Required: True

    • Possible values: "custom"

  • filename

    • Pretty name: Source filename

    • Description: The hdf5 filename of the source.

    • Parameter type: string

    • Required: True

  • dataset_name

    • Pretty name: Dataset name

    • Description: The hdf5 dataset name containing the source time function.

    • Parameter type: string

    • Required: True

Gradient subgroup [adjoint.gradient]

Model parameters and output filename for gradient computation.

Required: True

Full example (Please note that some options might be mutally exclusive):

[adjoint.gradient]
    parameterization = "rho-vp-vs"
    output_filename = "gradient.h5"
    format = "hdf5"
{
  "gradient": {
    "parameterization": "rho-vp-vs",
    "output_filename": "gradient.h5",
    "format": "hdf5"
  }
}

Detailed description of all parameters:

  • parameterization

    • Pretty name: Parameterization

    • Description: Parameterization of this gradeint

    • Parameter type: string

    • Required: True

    • Possible values: "linear", "rho-vp", "rho-vp-vs", "impedance", "love-parameters", "tti"

  • output_filename

    • Pretty name: Output file name

    • Description: File within which to store the gradient

    • Parameter type: string

    • Required: True

  • format

    • Pretty name: File format

    • Description: The file format for the gradient output.

    • Parameter type: string

    • Required: False

    • Possible values: "hdf5", "hdf5-full", "hdf5-minimal"

Domain group [domain]

This groups describes the physical domain in which to run simulations.

Required: True

Full example (Please note that some options might be mutally exclusive):

[domain]
    dimension = 3
    polynomial_order = 4
    [domain.mesh]
        filename = "mesh.h5"
        format = "hdf5"
    [domain.model]
        filename = "model.h5"
        format = "hdf5"
    [domain.geometry]
        filename = "geometry.h5"
        format = "hdf5"
{
  "domain": {
    "dimension": 3,
    "polynomial_order": 4,
    "mesh": {
      "filename": "mesh.h5",
      "format": "hdf5"
    },
    "model": {
      "filename": "model.h5",
      "format": "hdf5"
    },
    "geometry": {
      "filename": "geometry.h5",
      "format": "hdf5"
    }
  }
}

Detailed description of all parameters:

  • dimension

    • Pretty name: Dimension

    • Description: The spatial dimension of the problem.

    • Parameter type: integer

    • Required: True

    • Possible values: 2, 3

  • polynomial_order

    • Pretty name: Polynomial order

    • Description: Polynomial order of the spectral elements.

    • Parameter type: integer

    • Required: True

    • Possible values: 1, 2, 3, 4, 5, 6, 7

Mesh subgroup [domain.mesh]

Specify the domain topology.

Required: True

Full example (Please note that some options might be mutally exclusive):

[domain.mesh]
    filename = "mesh.h5"
    format = "hdf5"
{
  "mesh": {
    "filename": "mesh.h5",
    "format": "hdf5"
  }
}

Detailed description of all parameters:

  • filename

    • Pretty name: Mesh filename

    • Description: The filename of the mesh.

    • Parameter type: string

    • Required: True

  • format

    • Pretty name: Mesh format

    • Description: The format of the mesh.

    • Parameter type: string

    • Required: True

    • Possible values: "hdf5"

Model subgroup [domain.model]

Specify the physical parameters of the domain.

Required: True

Full example (Please note that some options might be mutally exclusive):

[domain.model]
    filename = "model.h5"
    format = "hdf5"
{
  "model": {
    "filename": "model.h5",
    "format": "hdf5"
  }
}

Detailed description of all parameters:

  • filename

    • Pretty name: Model filename

    • Description: The filename of the model.

    • Parameter type: string

    • Required: True

  • format

    • Pretty name: Model format

    • Description: The format of the model.

    • Parameter type: string

    • Required: True

    • Possible values: "hdf5"

Geometry subgroup [domain.geometry]

Specify the geometry of the domain.

Required: True

Full example (Please note that some options might be mutally exclusive):

[domain.geometry]
    filename = "geometry.h5"
    format = "hdf5"
{
  "geometry": {
    "filename": "geometry.h5",
    "format": "hdf5"
  }
}

Detailed description of all parameters:

  • filename

    • Pretty name: Filename

    • Description: The filename containing the geometry information.

    • Parameter type: string

    • Required: True

  • format

    • Pretty name: Geometry format

    • Description: The format of the geometry.

    • Parameter type: string

    • Required: True

    • Possible values: "hdf5"

Hardware group [hardware]

This groups describes the hardware and job specific parameters.

Required: False

Full example (Please note that some options might be mutally exclusive):

[hardware]
    gpu = false
{
  "hardware": {
    "gpu": false
  }
}

Detailed description of all parameters:

  • gpu

    • Pretty name: Enable GPU support

    • Description: Run simulation on GPUs

    • Parameter type: boolean

    • Required: True

Output group [output]

Simulation without output only have limited use. Specify point, surface, and volumetric outputs here.

Required: False

Full example (Please note that some options might be mutally exclusive):