Skip to main content
`Ctrl`+`K`

# External API

## SCons Extensions

class waves.scons_extensions.AbaqusPseudoBuilder(builder: Builder, override_cpus: int | None = None)

  Bases: `object`

  Abaqus Pseudo-Builder class which allows users to customize the Abaqus Pseudo-Builder.

  Parameters:

    - builder – A Builder generated by `waves.scons_extensions.abaqus_solver_builder_factory()`

    - override_cpus – Override the task-specific default number of CPUs. This kwarg value is most useful if propagated from a user-specified option at execution time. If None, Abaqus Pseudo-Builder tasks will use the task-specific default.

  Warning

  You must use an AbaqusSolver Builder generated from `waves.scons_extensions.abaqus_solver_builder_factory()`. Using the non-builder-factory `waves.scons_extensions.abaqus_solver()` (i.e. a Builder that does not use the `program_options` kwarg) is not supported.

  __call__(
    env: SConsEnvironment,
    job: str,
    inp: str | None = None,
    user: str | None = None,
    cpus: int = 1,
    oldjob: List[str] | str | None = None,
    write_restart: bool = False,
    double: str = 'both',
    extra_sources: List[str] | None = None,
    extra_targets: List[str] | None = None,
    extra_options: str = '',
    **kwargs,
  ) → NodeList

    SCons Pseudo-Builder for running Abaqus jobs.

    This SCons Pseudo-Builder wraps the WAVES Abaqus builders to automatically adjust the Abaqus command, sources list, and target list when specifying restart jobs and user subroutines.

    Note

    Restart files that are only used by Abaqus/Explicit (i.e. `.abq`, `.pac`, and `.sel`) are not currently added to the source and target lists when specifying `oldjob` or `write_restart`. Use `extra_sources` and `extra_targets` to manually add them when needed.

    Parameters:

      - job – Abaqus job name without file extension.

      - inp – Abaqus input file name with file extension. Defaults to `job`.inp.

      - user – User subroutine.

      - cpus – CPUs to use for simulation. Is superceded by `override_cpus` if provided during object instantiation. The CPUs option is escaped in the action string, i.e. changing the number of CPUs will not trigger a rebuild.

      - oldjob – Name of job(s) to restart/import. If a single old job is specified, “-oldjob” will be added to the Abaqus command. If multiple old jobs are specified, “-oldjob” will not be added to the Abaqus command (users should use the `*IMPORT, LIBRARY=` syntax in the Abaqus input file).

      - write_restart – If True, add restart files to target list. This is required if you want to use these restart files for a restart job.

      - double – Passthrough option for Abaqus’ `-double ${double}`.

      - extra_sources – Additional sources to supply to builder.

      - extra_targets – Additional targets to supply to builder.

      - extra_options – Additional Abaqus options to supply to builder. Should not include any Abaqus options available as kwargs, e.g. cpus, oldjob, user, input, job.

      - kwargs – Any additional kwargs are passed through to the builder.

    Returns:

      All targets associated with Abaqus simulation.

    SConstruct

        import waves
        # Allow user to override simulation-specific default number of CPUs
        AddOption('--solve-cpus', type='int')
        env = Environment()
        env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
        env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
        env.Append(BUILDERS={
            "AbaqusSolver": waves.scons_extensions.abaqus_solver_builder_factory(
                program=env["ABAQUS_PROGRAM"]
            )
        })
        env.AddMethod(
            waves.scons_extensions.AbaqusPseudoBuilder(
                builder=env.AbaqusSolver,
                override_cpus=env.GetOption("solve_cpus")),
            "Abaqus",
        )

    To define a simple Abaqus simulation:

        env.Abaqus(job='simulation_1')

    The job name can differ from the input file name:

        env.Abaqus(job='assembly_simulation_1', inp='simulation_1.inp')

    Specifying a user subroutine automatically adds the user subroutine to the source list:

        env.Abaqus(job='simulation_1', user='user.f')

    If you write restart files, you can add the restart files to the target list with:

        env.Abaqus(job='simulation_1', write_restart=True)

    This is important when you expect to use the restart files, as SCons will know to check that the required restart files exist and are up-to-date:

        env.Abaqus(job='simulation_2', oldjob='simulation_1')

    Multiple previous jobs can be specified if the Abaqus simulation imports from multiple ODBs:

        env.Abaqus(job='simulation_2', oldjob=['simulation_1', 'simulation_1a'])

    If your Abaqus job depends on files which aren’t detected by an implicit dependency scanner, you can add them to the source list directly:

        env.Abaqus(job='simulation_1', user='user.f', extra_sources=['user_subroutine_input.csv'])

    You can specify the default number of CPUs for the simulation:

        env.Abaqus(job='simulation_1', cpus=4)

class waves.scons_extensions.QOIPseudoBuilder(

  collection_dir: Path,
  build_dir: Path,
  update_expected: bool = False,
  _program: str = 'waves',

)

  Bases: `object`

  SCons Pseudo-Builder class which allows users to customize the QOI Pseudo-Builder.

  Warning

  This pseudo-builder is considered experimental pending early adopter end user trial and feedback.

  The QOI xarray data array and dataset handling for expected/calculated comparisons should be stable, but the output plotting and reporting formatting is subject to change.

  Parameters:

    - collection_dir – Root directory of QOI archive artifacts.

    - build_dir – Root directory of SCons project build artifacts.

    - updated_expected – Update the expected QOI CSV source files to match the calculated QOI values instead of comparing the calculated and expected values.

    - _program – The WAVES command line program call. Intended for internal use by developers to perform in-repository system testing. End users should not change the default value of this argument.

  __call__(
    env: SConsEnvironment,
    calculated: Path,
    expected: Path | None = None,
    archive: bool = False,
  ) → NodeList

    SCons Pseudo-Builder for regression testing and archiving quantities of interest (QOIs).

    This SCons Pseudo-Builder provides a convenient method for archiving and regression testing QOIs (such as critical simulation outputs). When requested, it aggregates the calculated values in a directory for easy archival. If expected values are specified, it compares them to the calculated values and reports any differences to a CSV file. If there are differences which exceed the user-specified tolerances, an error is raised. If `self.update_expected` is `True`, the expected CSV files (in the source tree) will be updated to match the calculated QOI values, and no comparison between the two will be performed.

    Parameters:

      - calculated – Path to CSV file containing calculated QOIs. See `qoi.read_qoi_set()` for the CSV format.

      - expected –

        Path to CSV file containing expected QOI values and tolerances. See `qoi.read_qoi_set()` for the CSV format. See `qoi.create_qoi()` for the types of tolerances allowed. See qoi for how tolerances are checked.

        Each of the tolerances are checked independently. If any fail, an error is raised.

        If `expected` is not specified, then QOIs are archived but not compared to expected values. Either `expected` or `archive=True` must be specified. An expected QOI file without tolerances is meaningless; the regression test will always pass.

      - archive – If True, add the calculated QOIs to `self.collection_dir` alongside other archived QOIs. To complete the archive, the QOI files collected in `self.collection_dir` should be copied to a read-only central location using `waves qoi archive`

    Returns:

      list of SCons Target. The list of targets associated with regression testing and archiving the QOIs. Building these targets will regression test the QOIs and output a CSV file which contains the exact differences between calculated and expected values. If `archive == True`, these targets will also include moving the calculated QOIs CSV file to the collection directory.

class waves.scons_extensions.WAVESEnvironment(

  *args,
  ABAQUS_PROGRAM: str = 'abaqus',
  ANSYS_PROGRAM: str = 'ansys',
  CCX_PROGRAM: str = 'ccx',
  CHARMRUN_PROGRAM: str = 'charmrun',
  FIERRO_EXPLICIT_PROGRAM: str = 'fierro-parallel-explicit',
  FIERRO_IMPLICIT_PROGRAM: str = 'fierro-parallel-implicit',
  INCITER_PROGRAM: str = 'inciter',
  MPIRUN_PROGRAM: str = 'mpirun',
  PYTHON_PROGRAM: str = 'python',
  SIERRA_PROGRAM: str = 'sierra',
  SPHINX_BUILD_PROGRAM: str = 'sphinx-build',
  **kwargs,

)

  Bases: `SConsEnvironment`

  Thin overload of SConsEnvironment with WAVES construction environment methods and builders

  AbaqusDatacheck(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.abaqus_solver_builder_factory()` using the `waves.scons_extensions.abaqus_datacheck_emitter()`.

    Variables:

      - program – `${ABAQUS_PROGRAM}`

      - emitter – `waves.scons_extensions.abaqus_datacheck_emitter()`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  AbaqusExplicit(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.abaqus_solver_builder_factory()` using the `waves.scons_extensions.abaqus_explicit_emitter()`.

    Variables:

      - program – `${ABAQUS_PROGRAM}`

      - emitter – `waves.scons_extensions.abaqus_explicit_emitter()`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  AbaqusJournal(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.abaqus_journal_builder_factory()`

    Variables:

      program – `${ABAQUS_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  AbaqusPseudoBuilder(job, *args, override_cpus: int | None = None, **kwargs)

    Construction environment pseudo-builder from `waves.scons_extensions.AbaqusPseudoBuilder`

    When using this environment pseudo-builder, do not provide the first `env` argument

    Parameters:

      - job – Abaqus job name.

      - override_cpus – Override the task-specific default number of CPUs. This kwarg value is most useful if propagated from a user-specified option at execution time. If None, Abaqus Pseudo-Builder tasks will use the task-specific default.

      - args – All other positional arguments are passed through to `waves.scons_extensions.AbaqusPseudoBuilder.__call__`()`

      - kwargs – All other keyword arguments are passed through to `waves.scons_extensions.AbaqusPseudoBuilder.__call__`()`

  AbaqusSolver(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.abaqus_solver_builder_factory()`

    Variables:

      program – `${ABAQUS_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  AbaqusStandard(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.abaqus_solver_builder_factory()` using the `waves.scons_extensions.abaqus_standard_emitter()`.

    Variables:

      - program – `${ABAQUS_PROGRAM}`

      - emitter – `waves.scons_extensions.abaqus_standard_emitter()`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  AddCubit(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.add_cubit()`

    When using this environment method, do not provide the first `env` argument

  AddCubitPython(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.add_cubit_python()`

    When using this environment method, do not provide the first `env` argument

  AddProgram(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.add_program()`

    When using this environment method, do not provide the first `env` argument

  AnsysAPDL(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.ansys_apdl_builder_factory()`

    Variables:

      program – `${ANSYS_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  CalculiX(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.calculix_builder_factory()`

    Variables:

      program – `${CCX_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  CheckProgram(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.check_program()`

    When using this environment method, do not provide the first `env` argument

  CopySubstfile(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.copy_substfile()`

    When using this environment method, do not provide the first `env` argument

  FierroExplicit(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.fierro_explicit_builder_factory()`

    Variables:

      - program – `${MPIRUN_PROGRAM}`

      - subcommand – `${FIERRO_EXPLICIT_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  FierroImplicit(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.fierro_implicit_builder_factory()`

    Variables:

      - program – `${MPIRUN_PROGRAM}`

      - subcommand – `${FIERRO_IMPLICIT_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  FindProgram(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.find_program()`

    When using this environment method, do not provide the first `env` argument

  FirstTargetBuilder(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.first_target_builder_factory()`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  ParameterStudySConscript(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.parameter_study_sconscript()`

    When using this environment method, do not provide the first `env` argument

  ParameterStudyTask(*args, **kwargs)

    Construction environment pseudo-builder from `waves.scons_extensions.parameter_study_task()`

    When using this environment pseudo-builder, do not provide the first `env` argument

  ParameterStudyWrite(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.parameter_study_write()`

    When using this environment method, do not provide the first `env` argument

  PrintBuildFailures(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.print_build_failures()`

    When using this environment method, do not provide the first `env` argument

  ProjectAlias(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.project_alias()`

    When using this environment method, do not provide the first `env` argument

  ProjectHelp(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.project_help()`

    When using this environment method, do not provide the first `env` argument

  PythonScript(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.python_builder_factory()`

    Variables:

      program – `${PYTHON_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  QuinoaSolver(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.quinoa_builder_factory()`

    Variables:

      - program – `${CHARMRUN_PROGRAM}`

      - subcommand – `${INCITER_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  Sierra(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.sierra_builder_factory()`

    Variables:

      program – `${SIERRA_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  SphinxBuild(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.sphinx_build()`

    Variables:

      program – `${SPHINX_BUILD_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  SphinxPDF(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.sphinx_latexpdf()`

    Variables:

      program – `${SPHINX_BUILD_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

  SubstitutionSyntax(*args, **kwargs)

    Construction environment method from `waves.scons_extensions.substitution_syntax()`

    When using this environment method, do not provide the first `env` argument

  Truchas(target, source, *args, **kwargs)

    Builder from factory `waves.scons_extensions.truchas_builder_factory()`

    Variables:

      - program – `${MPIRUN_PROGRAM}`

      - subcommand – `${TRUCHAS_PROGRAM}`

    Parameters:

      - target – The task target list

      - source – The task source list

      - args – All positional arguments are passed through to the builder (not to the builder factory)

      - kwargs – All keyword arguments are passed through to the builder (not to the builder factory)

waves.scons_extensions.abaqus_datacheck_emitter(

  target: list,
  source: list,
  env: SConsEnvironment,
  suffixes: Iterable[str] = ('.odb', '.dat', '.msg', '.com', '.prt', '.023', '.mdl', '.sim', '.stt'),
  appending_suffixes: Iterable[str] | None = None,
  stdout_extension: str = '.stdout',

)

  Abaqus solver emitter for datacheck targets

  SCons emitter for `waves.scons_extensions.abaqus_solver_builder_factory()` based builders. Built on `waves.scons_extensions.abaqus_solver_emitter_factory()`.

  Appends the target list with `job` task keyword argument named targets before passing through the `waves.scons_extensions.first_target_emitter()` emitter.

  Searches for the `job` task keyword argument and appends the target list with `f"{job}{suffix}"` targets using the `suffixes` list.

  Searches for a file ending in the stdout extension. If none is found, creates a target by appending the stdout extension to the first target in the `target` list. The associated Builder requires at least one target for this reason. The stdout file is always placed at the end of the returned target list.

  This is an SCons emitter function and not an emitter factory. The suffix arguments: `suffixes` and `appending_suffixes` are only relevant for developers writing new emitters which call this function as a base. The suffixes list emits targets where the suffix replaces the first target’s suffix, e.g. for `target.ext` emit a new target `target.suffix`. The appending suffixes list emits targets where the suffix appends the first target’s suffix, e.g. for `target.ext` emit a new target `target.ext.appending_suffix`.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/target.ext`. When in doubt, provide a STDOUT redirect file with the `.stdout` extension as a target, e.g. `target.stdout` or `parameter_set1/target.stdout`.

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={
          "AbaqusDatacheck": waves.scons_extensions.abaqus_solver_builder_factory(
              program=env["ABAQUS_PROGRAM"],
              emitter=waves.scons_extensions.abaqus_datacheck_emitter,
          )
      })
      env.AbaqusDatacheck(target=["job.odb"], source=["input.inp"], job="job")

  Note

  The `job` keyword argument must be provided in the task definition.

  Parameters:

    - target – The target file list of strings

    - source – The source file list of SCons.Node.FS.File objects

    - env – The builder’s SCons construction environment object

    - suffixes – Suffixes which should replace the first target’s extension

    - appending_suffixes – Suffixes which should append the first target’s extension

    - stdout_extension – The extension used by the STDOUT/STDERR redirect file

  Returns:

    target, source

waves.scons_extensions.abaqus_explicit_emitter(

  target: list,
  source: list,
  env: SConsEnvironment,
  suffixes: Iterable[str] = ('.odb', '.dat', '.msg', '.com', '.prt', '.sta'),
  appending_suffixes: Iterable[str] | None = None,
  stdout_extension: str = '.stdout',

)

  Abaqus solver emitter for Explicit targets

  SCons emitter for `waves.scons_extensions.abaqus_solver_builder_factory()` based builders. Built on `waves.scons_extensions.abaqus_solver_emitter_factory()`.

  Appends the target list with `job` task keyword argument named targets before passing through the `waves.scons_extensions.first_target_emitter()` emitter.

  Searches for the `job` task keyword argument and appends the target list with `f"{job}{suffix}"` targets using the `suffixes` list.

  Searches for a file ending in the stdout extension. If none is found, creates a target by appending the stdout extension to the first target in the `target` list. The associated Builder requires at least one target for this reason. The stdout file is always placed at the end of the returned target list.

  This is an SCons emitter function and not an emitter factory. The suffix arguments: `suffixes` and `appending_suffixes` are only relevant for developers writing new emitters which call this function as a base. The suffixes list emits targets where the suffix replaces the first target’s suffix, e.g. for `target.ext` emit a new target `target.suffix`. The appending suffixes list emits targets where the suffix appends the first target’s suffix, e.g. for `target.ext` emit a new target `target.ext.appending_suffix`.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/target.ext`. When in doubt, provide a STDOUT redirect file with the `.stdout` extension as a target, e.g. `target.stdout` or `parameter_set1/target.stdout`.

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={
          "AbaqusExplicit": waves.scons_extensions.abaqus_solver_builder_factory(
              program=env["ABAQUS_PROGRAM"],
              emitter=waves.scons_extensions.abaqus_explicit_emitter,
          )
      })
      env.AbaqusExplicit(target=["job.odb"], source=["input.inp"], job="job")

  Note

  The `job` keyword argument must be provided in the task definition.

  Parameters:

    - target – The target file list of strings

    - source – The source file list of SCons.Node.FS.File objects

    - env – The builder’s SCons construction environment object

    - suffixes – Suffixes which should replace the first target’s extension

    - appending_suffixes – Suffixes which should append the first target’s extension

    - stdout_extension – The extension used by the STDOUT/STDERR redirect file

  Returns:

    target, source

waves.scons_extensions.abaqus_extract(program: str = 'abaqus') → Builder

  Abaqus ODB file extraction Builder

  This builder executes the `odb_extract` command line utility against an ODB file in the source list. The ODB file must be the first file in the source list. If there is more than one ODB file in the source list, all but the first file are ignored by `odb_extract`.

  This builder is unique in that no targets are required. The Builder emitter will append the builder managed targets and `odb_extract` target name constructions automatically. The first target determines the working directory for the emitter targets. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then at least one target must be provided with the build subdirectory, e.g. `parameter_set1/target.h5`. When in doubt, provide the expected H5 file as a target, e.g. `source[0].h5`.

  The target list may specify an output H5 file name that differs from the ODB file base name as `new_name.h5`. If the first file in the target list does not contain the `*.h5` extension, or if there is no file in the target list, the target list will be prepended with a name matching the ODB file base name and the `*.h5` extension.

  The builder emitter appends the CSV file created by the `abaqus odbreport` command as executed by `odb_extract` unless `delete_report_file` is set to `True`.

  This builder supports the keyword arguments: `output_type`, `odb_report_args`, `delete_report_file` with behavior as described in the ODB Extract command line interface.

  Format of HDF5 file

      /                 # Top level group required in all hdf5 files
      /<instance name>/ # Groups containing data of each instance found in an odb
          FieldOutputs/      # Group with multiple xarray datasets for each field output
              <field name>/  # Group with datasets containing field output data for a specified set or surface
                             # If no set or surface is specified, the <field name> will be
                             # 'ALL_NODES' or 'ALL_ELEMENTS'
          HistoryOutputs/    # Group with multiple xarray datasets for each history output
              <region name>/ # Group with datasets containing history output data for specified history region name
                             # If no history region name is specified, the <region name> will be 'ALL NODES'
          Mesh/              # Group written from an xarray dataset with all mesh information for this instance
      /<instance name>_Assembly/ # Group containing data of assembly instance found in an odb
          Mesh/              # Group written from an xarray dataset with all mesh information for this instance
      /odb/             # Catch all group for data found in the odbreport file not already organized by instance
          info/              # Group with datasets that mostly give odb meta-data like name, path, etc.
          jobData/           # Group with datasets that contain additional odb meta-data
          rootAssembly/      # Group with datasets that match odb file organization per Abaqus documentation
          sectionCategories/ # Group with datasets that match odb file organization per Abaqus documentation
      /xarray/          # Group with a dataset that lists the location of all data written from xarray datasets

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={"AbaqusExtract": waves.scons_extensions.abaqus_extract()})
      env.AbaqusExtract(target=["my_job.h5", "my_job.csv"], source=["my_job.odb"])

  Parameters:

    program – An absolute path or basename string for the abaqus program

  Returns:

    Abaqus extract builder

waves.scons_extensions.abaqus_input_scanner() → Scanner

  Abaqus input file dependency scanner

  Custom SCons scanner that searches for the `INPUT=` parameter and associated file dependencies inside Abaqus `*.inp` files.

  Returns:

    Abaqus input file dependency Scanner

waves.scons_extensions.abaqus_journal(

  program: str = 'abaqus',
  required: str = 'cae -noGUI ${SOURCE.abspath}',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  environment_suffix: str = '> ${TARGETS[-2].abspath} 2>&1',

) → Builder

  Construct and return an Abaqus journal file SCons builder

  This builder requires that the journal file to execute is the first source in the list. The builder returned by this function accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the keyword arguments override the builder returned by this function.

  Builder/Task keyword arguments

  - `program`: The Abaqus command line executable absolute or relative path

  - `required`: A space delimited string of Abaqus required arguments

  - `abaqus_options`: The Abaqus command line options provided as a string

  - `journal_options`: The journal file command line options provided as a string

  - `action_prefix`: Advanced behavior. Most users should accept the defaults

  - `action_suffix`: Advanced behavior. Most users should accept the defaults.

  - `environment_suffix`: Advanced behavior. Most users should accept the defaults.

  At least one target must be specified. The first target determines the working directory for the builder’s action, as shown in the action code snippet below. The action changes the working directory to the first target’s parent directory prior to executing the journal file.

  The Builder emitter will append the builder managed targets automatically. Appends `target[0]`.abaqus_v6.env and `target[0]`.stdout to the `target` list.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/my_target.ext`. When in doubt, provide a STDOUT redirect file as a target, e.g. `target.stdout`.

  Abaqus journal builder action keywords

      ${action_prefix} ${program} -information environment ${environment_suffix}
      ${action_prefix} ${program} ${required} ${abaqus_options} -- ${journal_options} ${action_suffix}

  With the default argument values, this expands to

  Abaqus journal builder action default expansion

      cd ${TARGET.dir.abspath} && abaqus -information environment > ${TARGETS[-2].abspath} 2>&1
      cd ${TARGET.dir.abspath} && abaqus cae -noGui ${SOURCE.abspath} ${abaqus_options} -- ${journal_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={"AbaqusJournal": waves.scons_extensions.abaqus_journal()})
      env.AbaqusJournal(target=["my_journal.cae"], source=["my_journal.py"], journal_options="")

  Parameters:

    - program – The Abaqus command line executable absolute or relative path

    - required – A space delimited string of Abaqus required arguments

    - action_prefix – Advanced behavior. Most users should accept the defaults.

    - action_suffix – Advanced behavior. Most users should accept the defaults.

    - environment_suffix – Advanced behavior. Most users should accept the defaults.

  Returns:

    Abaqus journal builder

waves.scons_extensions.abaqus_journal_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'abaqus',
  program_required: str = 'cae -noGUI ${SOURCES[0].abspath}',
  program_options: str = '',
  subcommand: str = '--',
  subcommand_required: str = '',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Abaqus journal builder factory

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  With the default options this builder requires the following sources file provided in the order:

  1. Abaqus journal file: `*.py`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && abaqus cae -noGUI=${SOURCES[0].abspath} ${program_options} -- ${subcommand_required} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={
          "AbaqusJournal": waves.scons_extensions.abaqus_journal_builder_factory(
              program=env["ABAQUS_PROGRAM"]
          )
      })
      env.AbaqusJournal(target=["my_journal.cae"], source=["my_journal.py"])

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The Abaqus absolute or relative path

    - program_required – Space delimited string of required Abaqus options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional Abaqus options and arguments that can be freely modified by the user

    - subcommand – The shell separator for positional arguments used to separate Abaqus program from Abaqus journal file arguments and options

    - subcommand_required – Space delimited string of required Abaqus journal file options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional Abaqus journal file options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Abaqus journal builder

waves.scons_extensions.abaqus_solver(

  program: str = 'abaqus',
  required: str = '-interactive -ask_delete no -job ${job_name} -input ${SOURCE.filebase}',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  environment_suffix: str = '> ${TARGETS[-2].abspath} 2>&1',
  emitter: Literal['standard', 'explicit', 'datacheck', None] = None,

) → Builder

  Construct and return an Abaqus solver SCons builder

  This builder requires that the root input file is the first source in the list. The builder returned by this function accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the keyword arguments override the builder returned by this function.

  Builder/Task keyword arguments

  - `program`: The Abaqus command line executable absolute or relative path

  - `required`: A space delimited string of Abaqus required arguments

  - `job_name`: The job name string. If not specified `job_name` defaults to the root input file stem. The Builder

      emitter will append common Abaqus output files as targets automatically from the `job_name`, e.g. `job_name.odb`.

  - `abaqus_options`: The Abaqus command line options provided as a string.

  - `suffixes`: override the emitter targets with a new list of extensions, e.g. `AbaqusSolver(target=[], source=["input.inp"], suffixes=[".odb"])` will emit only one file named `job_name.odb`.

  - `action_prefix`: Advanced behavior. Most users should accept the defaults

  - `action_suffix`: Advanced behavior. Most users should accept the defaults.

  - `environment_suffix`: Advanced behavior. Most users should accept the defaults.

  The first target determines the working directory for the builder’s action, as shown in the action code snippet below. The action changes the working directory to the first target’s parent directory prior to executing the journal file.

  This builder is unique in that no targets are required. The Builder emitter will append the builder managed targets automatically. The target list only appends those extensions which are common to Abaqus analysis operations. Some extensions may need to be added explicitly according to the Abaqus simulation solver, type, or options. If you find that SCons isn’t automatically cleaning some Abaqus output files, they are not in the automatically appended target list.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/job_name.odb`. When in doubt, provide a STDOUT redirect file as a target, e.g. `target.stdout`.

  The `-interactive` option is always appended to the builder action to avoid exiting the Abaqus task before the simulation is complete. The `-ask_delete no` option is always appended to the builder action to overwrite existing files in programmatic execution, where it is assumed that the Abaqus solver target(s) should be re-built when their source files change.

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={
          "AbaqusSolver": waves.scons_extensions.abaqus_solver(),
          "AbaqusStandard": waves.scons_extensions.abaqus_solver(emitter='standard'),
          "AbaqusOld": waves.scons_extensions.abaqus_solver(program="abq2019")
      })
      env.AbaqusSolver(target=[], source=["input.inp"], job_name="my_job", abaqus_options="-cpus 4")
      env.AbaqusSolver(target=[], source=["input.inp"], job_name="my_job", suffixes=[".odb"])

  Abaqus solver builder action keywords

      ${action_prefix} ${program} -information environment ${environment_suffix}
      ${action_prefix} ${program} ${required} ${abaqus_options} ${action_suffix}

  Abaqus solver builder action default expansion

      cd ${TARGET.dir.abspath} && abaqus -information environment > ${TARGETS[-2].abspath} 2>&1
      cd ${TARGET.dir.abspath} && ${program} -interactive -ask_delete no -job ${job_name} -input ${SOURCE.filebase} ${abaqus_options} > ${TARGETS[-1].abspath} 2>&1

  Parameters:

    - program – An absolute path or basename string for the abaqus program

    - required – A space delimited string of Abaqus required arguments

    - action_prefix – Advanced behavior. Most users should accept the defaults.

    - action_suffix – Advanced behavior. Most users should accept the defaults.

    - environment_suffix – Advanced behavior. Most users should accept the defaults.

    - emitter –

      emit file extensions based on the value of this variable. Overridden by the `suffixes` keyword argument that may be provided in the Task definition.

      - ”standard”: [“.odb”, “.dat”, “.msg”, “.com”, “.prt”, “.sta”]

      - ”explicit”: [“.odb”, “.dat”, “.msg”, “.com”, “.prt”, “.sta”]

      - ”datacheck”: [“.odb”, “.dat”, “.msg”, “.com”, “.prt”, “.023”, “.mdl”, “.sim”, “.stt”]

      - default value: [“.odb”, “.dat”, “.msg”, “.com”, “.prt”]

  Returns:

    Abaqus solver builder

waves.scons_extensions.abaqus_solver_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'abaqus',
  program_required: str = '-interactive -ask_delete no -job ${job} -input ${SOURCE.filebase}',
  program_options: str = '',
  subcommand: str = '',
  subcommand_required: str = '',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Abaqus solver builder factory

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  With the default options this builder requires the following sources file provided in the order:

  1. Abaqus solver file: `*.inp`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && abaqus -interactive -ask_delete no -job ${job} -input ${SOURCE.filebase} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={
          "AbaqusSolver": waves.scons_extensions.abaqus_solver_builder_factory(
              program=env["ABAQUS_PROGRAM"]
          )
      })
      env.AbaqusSolver(target=["job.odb"], source=["input.inp"], job="job")

  Note

  The `job` keyword argument must be provided in the task definition.

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The Abaqus absolute or relative path

    - program_required – Space delimited string of required Abaqus options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional Abaqus options and arguments that can be freely modified by the user

    - subcommand – The subcommand absolute or relative path

    - subcommand_required – Space delimited string of required subcommand options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional subcommand options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Abaqus solver builder

waves.scons_extensions.abaqus_solver_emitter_factory(

  suffixes: Iterable[str] = ('.odb', '.dat', '.msg', '.com', '.prt'),
  appending_suffixes: Iterable[str] | None = None,
  stdout_extension: str = '.stdout',

) → Callable[[list, list, SConsEnvironment], tuple]

  Abaqus solver emitter factory

  SCons emitter factory that returns emitters for `waves.scons_extensions.abaqus_solver_builder_factory()` based builders.

  Emitters returned by this factory append the target list with `job` task keyword argument named targets before passing through the `waves.scons_extensions.first_target_emitter()` emitter.

  Searches for the `job` task keyword argument and appends the target list with `f"{job}{suffix}"` targets using the `suffixes` list.

  Searches for a file ending in the stdout extension. If none is found, creates a target by appending the stdout extension to the first target in the `target` list. The associated Builder requires at least one target for this reason. The stdout file is always placed at the end of the returned target list.

  The `suffixes` list emits targets where the suffix replaces the first target’s suffix, e.g. for `target.ext` emit a new target `target.suffix`. The appending suffixes list emits targets where the suffix appends the first target’s suffix, e.g. for `target.ext` emit a new target `target.ext.appending_suffix`.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/target.ext`. When in doubt, provide a STDOUT redirect file with the `.stdout` extension as a target, e.g. `target.stdout` or `parameter_set1/target.stdout`.

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={
          "AbaqusStandard": waves.scons_extensions.abaqus_solver_builder_factory(
              program=env["ABAQUS_PROGRAM"],
              emitter=waves.scons_extensions.abaqus_solver_emitter_factory(
                  suffixes=[".odb", ".dat", ".msg", ".com", ".prt", ".sta"],
              )
          )
      })
      env.AbaqusStandard(target=["job.odb"], source=["input.inp"], job="job")

  Note

  The `job` keyword argument must be provided in the task definition.

  Parameters:

    - suffixes – Suffixes which should replace the first target’s extension

    - appending_suffixes – Suffixes which should append the first target’s extension

    - stdout_extension – The extension used by the STDOUT/STDERR redirect file

  Returns:

    emitter function

waves.scons_extensions.abaqus_standard_emitter(

  target: list,
  source: list,
  env: SConsEnvironment,
  suffixes: Iterable[str] = ('.odb', '.dat', '.msg', '.com', '.prt', '.sta'),
  appending_suffixes: Iterable[str] | None = None,
  stdout_extension: str = '.stdout',

)

  Abaqus solver emitter for Standard targets

  SCons emitter for `waves.scons_extensions.abaqus_solver_builder_factory()` based builders. Built on `waves.scons_extensions.abaqus_solver_emitter_factory()`.

  Appends the target list with `job` task keyword argument named targets before passing through the `waves.scons_extensions.first_target_emitter()` emitter.

  Searches for the `job` task keyword argument and appends the target list with `f"{job}{suffix}"` targets using the `suffixes` list.

  Searches for a file ending in the stdout extension. If none is found, creates a target by appending the stdout extension to the first target in the `target` list. The associated Builder requires at least one target for this reason. The stdout file is always placed at the end of the returned target list.

  This is an SCons emitter function and not an emitter factory. The suffix arguments: `suffixes` and `appending_suffixes` are only relevant for developers writing new emitters which call this function as a base. The suffixes list emits targets where the suffix replaces the first target’s suffix, e.g. for `target.ext` emit a new target `target.suffix`. The appending suffixes list emits targets where the suffix appends the first target’s suffix, e.g. for `target.ext` emit a new target `target.ext.appending_suffix`.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/target.ext`. When in doubt, provide a STDOUT redirect file with the `.stdout` extension as a target, e.g. `target.stdout` or `parameter_set1/target.stdout`.

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ABAQUS_PROGRAM"] = env.AddProgram(["abaqus"])
      env.Append(BUILDERS={
          "AbaqusStandard": waves.scons_extensions.abaqus_solver_builder_factory(
              program=env["ABAQUS_PROGRAM"],
              emitter=waves.scons_extensions.abaqus_standard_emitter,
          )
      })
      env.AbaqusStandard(target=["job.odb"], source=["input.inp"], job="job")

  Note

  The `job` keyword argument must be provided in the task definition.

  Parameters:

    - target – The target file list of strings

    - source – The source file list of SCons.Node.FS.File objects

    - env – The builder’s SCons construction environment object

    - suffixes – Suffixes which should replace the first target’s extension

    - appending_suffixes – Suffixes which should append the first target’s extension

    - stdout_extension – The extension used by the STDOUT/STDERR redirect file

  Returns:

    target, source

waves.scons_extensions.action_list_scons(actions: Iterable[str]) → ListAction

  Convert a list of action strings to an SCons.Action.ListAction object

  Parameters:

    actions – List of action strings

  Returns:

    SCons.Action.ListAction object of SCons.Action.CommandAction

waves.scons_extensions.action_list_strings(builder: Builder) → List[str]

  Return a builder’s action list as a list of str

  Parameters:

    builder – The builder to extract the action list from

  Returns:

    list of builder actions

waves.scons_extensions.add_cubit(env: SConsEnvironment, names: Iterable[str]) → str

  Modifies environment variables with the paths required to `import cubit` in a Python3 environment.

  Returns the absolute path of the first program name found. Appends `PATH` with first program’s parent directory if a program is found and the directory is not already on `PATH`. Prepends `PYTHONPATH` with `parent/bin`. Prepends `LD_LIBRARY_PATH` with `parent/bin/python3`.

  Returns None if no program name is found.

  Example Cubit environment modification

      import waves

      env = Environment()
      env.AddMethod(waves.scons_extensions.add_cubit, "AddCubit")
      env["CUBIT_PROGRAM"] = env.AddCubit(["cubit"])

  Parameters:

    - env – The SCons construction environment object to modify

    - names – list of string program names for the main Cubit executable. May include an absolute path.

  Returns:

    Absolute path of the Cubit executable. None if none of the names are found.

waves.scons_extensions.add_cubit_python(env: SConsEnvironment, names: Iterable[str]) → str

  Modifies environment variables with the paths required to `import cubit` with the Cubit Python interpreter.

  Returns the absolute path of the first Cubit Python intepreter found. Appends `PATH` with Cubit Python parent directory if a program is found and the directory is not already on `PATH`. Prepends `PYTHONPATH` with `parent/bin`.

  Returns None if no Cubit Python interpreter is found.

  Example Cubit environment modification

      import waves

      env = Environment()
      env.AddMethod(waves.scons_extensions.add_cubit_python, "AddCubitPython")
      env["CUBIT_PROGRAM"] = env.AddCubitPython(["cubit"])

  Parameters:

    - env – The SCons construction environment object to modify

    - names – list of string program names for the main Cubit executable. May include an absolute path.

  Returns:

    Absolute path of the Cubit Python intepreter. None if none of the names are found.

waves.scons_extensions.add_program(env: SConsEnvironment, names: Iterable[str]) → str

  Search for a program from a list of possible program names. Add first found to system `PATH`.

  Returns the absolute path of the first program name found. Appends `PATH` with first program’s parent directory if a program is found and the directory is not already on `PATH`. Returns None if no program name is found.

  Example search for an executable named “program”

      import waves

      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["PROGRAM"] = env.AddProgram(["program"])

  Parameters:

    - env – The SCons construction environment object to modify

    - names – list of string program names. May include an absolute path.

  Returns:

    Absolute path of the found program. None if none of the names are found.

waves.scons_extensions.ansys_apdl_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'ansys',
  program_required: str = '-i ${SOURCES[0].abspath} -o ${TARGETS[-1].abspath}',
  program_options: str = '',
  subcommand: str = '',
  subcommand_required: str = '',
  subcommand_options: str = '',
  action_suffix: str = '',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Ansys APDL builder factory.

  Warning

  This is an experimental builder. It is subject to change without warning.

  Warning

  This builder does not have a tutorial and is not included in the regression test suite yet. Contact the development team if you encounter problems or have recommendations for improved design behavior.

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `program_required` option to match their emitter’s behavior.

  With the default options this builder requires the following sources file provided in the order:

  1. Ansys APDL file: `*.dat`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && ansys -i ${SOURCES[0].abspath} -o ${TARGETS[-1].abspath} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["ANSYS_PROGRAM"] = env.AddProgram(["ansys232"])
      env.Append(BUILDERS={
           "AnsysAPDL": waves.scons_extensions.ansys_apdl_builder_factory(
               program=env["ANSYS_PROGRAM"]
           )
      })
      env.AnsysAPDL(
          target=["job.rst"],
          source=["source.dat"],
          program_options="-j job"
      )

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The Ansys absolute or relative path

    - program_required – Space delimited string of required Ansys options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional Ansys options and arguments that can be freely modified by the user

    - subcommand – A subcommand absolute or relative path

    - subcommand_required – Space delimited string of required subcommand options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional subcommand options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Ansys builder

waves.scons_extensions.append_env_path(env: SConsEnvironment, program: str) → None

  Append SCons contruction environment `PATH` with the program’s parent directory

  Uses the SCons AppendENVPath method. If the program parent directory is already on `PATH`, the `PATH` directory order is preserved.

  Example environment modification

      import waves

      env = Environment()
      env["PROGRAM"] = waves.scons_extensions.find_program(env, ["program"])
      if env["PROGRAM"]:
          waves.append_env_path(env, env["PROGRAM"])

  Parameters:

    - env – The SCons construction environment object to modify

    - program – An absolute path for the program to add to SCons construction environment `PATH`

  Raises:

    FileNotFoundError – if the `program` absolute path does not exist.

waves.scons_extensions.builder_factory(

  environment: str = '',
  action_prefix: str = '',
  program: str = '',
  program_required: str = '',
  program_options: str = '',
  subcommand: str = '',
  subcommand_required: str = '',
  subcommand_options: str = '',
  action_suffix: str = '',
  emitter=None,
  **kwargs,

) → Builder

  Template builder factory returning a builder with no emitter

  This builder provides a template action string with placeholder keyword arguments in the action string. The default behavior will not do anything unless the `program` or `subcommand` argument is updated to include an executable program. Because this builder has no emitter, all task targets must be fully specified in the task definition. See `waves.scons_extensions.first_target_builder_factory()` for an example of the default options used by most WAVES builders.

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution. By default, SCons performs actions in the parent directory of the SConstruct file. However, many computational science and engineering programs leave output files in the current working directory, so it is convenient and sometimes necessary to change to the target’s parent directory prior to execution.

    - program – This variable is intended to contain the primary command line executable absolute or relative path

    - program_required – This variable is intended to contain a space delimited string of required program options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - program_options – This variable is intended to contain a space delimited string of optional program options and arguments that can be freely modified by the user.

    - subcommand – This variable is intended to contain the program’s subcommand. If the program variable is set to a launch controlling program, e.g. `mpirun` or `charmrun`, then the subcommand may need to contain the full target executable program and any subcommands.

    - subcommand_required – This variable is intended to contain a space delimited string of required subcommand options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – This variable is intended to contain a space delimited string of optional subcommand options and arguments that can be freely modified by the user.

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations. By default, SCons streams all STDOUT and STDERR to the terminal. However, in long or parallel workflows this may clutter the terminal and make it difficult to isolate critical debugging information, so it is convenient to redirect each program’s output to a task specific log file for later inspection and troubleshooting.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    SCons template builder

waves.scons_extensions.calculix_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'ccx',
  program_required: str = '-i ${SOURCE.filebase}',
  program_options: str = '',
  subcommand: str = '',
  subcommand_required: str = '',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  CalculiX builder factory.

  Warning

  This is an experimental builder. It is subject to change without warning.

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  Warning

  CalculiX always appends the `.inp` extension to the input file argument. Stripping the extension in the builder requires a file basename without preceding relative or absolute path. This builder is fragile to current working directory. Most users should not modify the `action_prefix`.

  With the default options this builder requires the following sources file provided in the order:

  1. CalculiX input file: `*.inp`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && ccx -i ${SOURCE.filebase} ${program_required} ${subcommand} ${subcommand_required} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["CCX_PROGRAM"] = env.AddProgram(["ccx"])
      env.Append(BUILDERS={
          "CalculiX": waves.scons_extensions.calculix_builder_factory(
              subcommand=env["CCX_PROGRAM"]
          )
      })
      env.CalculiX(
          target=["target.stdout"],
          source=["source.inp"],
      )

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The CalculiX `ccx` absolute or relative path

    - program_required – Space delimited string of required CalculiX options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional CalculiX options and arguments that can be freely modified by the user

    - subcommand – A subcommand absolute or relative path

    - subcommand_required – Space delimited string of required subcommand options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional subcommand options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    CalculiX builder

waves.scons_extensions.catenate_actions(**outer_kwargs)

  Decorator factory to apply the `catenate_builder_actions` to a function that returns an SCons Builder.

  Accepts the same keyword arguments as the `waves.scons_extensions.catenate_builder_actions()`

      import SCons.Builder
      import waves

      @waves.scons_extensions.catenate_actions
      def my_builder():
          return SCons.Builder.Builder(action=["echo $SOURCE > $TARGET", "echo $SOURCE >> $TARGET"])

waves.scons_extensions.catenate_builder_actions(

  builder: Builder,
  program: str = '',
  options: str = '',

) → Builder

  Catenate a builder’s arguments and prepend the program and options

      ${program} ${options} "action one && action two"

  Parameters:

    - builder – The SCons builder to modify

    - program – wrapping executable

    - options – options for the wrapping executable

  Returns:

    modified builder

waves.scons_extensions.check_program(env: SConsEnvironment, prog_name: str) → str

  Replacement for SCons CheckProg like behavior without an SCons configure object

  Example search for an executable named “program”

      import waves

      env = Environment()
      env.AddMethod(waves.scons_extensions.check_program, "CheckProgram")
      env["PROGRAM"] = env.CheckProgram(["program"])

  Parameters:

    - env – The SCons construction environment object to modify

    - prog_name – string program name to search in the construction environment path

waves.scons_extensions.conda_environment(

  program: str = 'conda',
  subcommand: str = 'env export',
  required: str = '--file ${TARGET.abspath}',
  options: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',

) → Builder

  Create a Conda environment file with `conda env export`

  This builder is intended to help WAVES workflows document the Conda environment used in the current build. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the keyword arguments override the builder returned by this function.

  Builder/Task keyword arguments

  - `program`: The Conda command line executable absolute or relative path

  - `subcommand`: The Conda environment export subcommand

  - `required`: A space delimited string of subcommand required arguments

  - `options`: A space delimited string of subcommand optional arguments

  - `action_prefix`: Advanced behavior. Most users should accept the defaults

  At least one target must be specified. The first target determines the working directory for the builder’s action, as shown in the action code snippet below. The action changes the working directory to the first target’s parent directory prior to creating the Conda environment file.

  Conda environment builder action default expansion

      ${action_prefix} ${program} ${subcommand} ${required} ${options}"

  Conda environment builder action default expansion

      cd ${TARGET.dir.abspath} && conda env export --file ${TARGET.abspath} ${options}

  The modsim owner may choose to re-use this builder throughout their project configuration to provide various levels of granularity in the recorded Conda environment state. It’s recommended to include this builder at least once for any workflows that also use the `waves.scons_extensions.python_builder_factory()`. The builder may be re-used once per build sub-directory to provide more granular build environment reproducibility in the event that sub-builds are run at different times with variations in the active Conda environment. For per-Python script task environment reproducibility, the builder source list can be linked to the output of a `waves.scons_extensions.python_builder_factory()` task with a target environment file name to match.

  The first recommendation, always building the project wide Conda environment file, is demonstrated in the example usage below.

  SConstruct

      import waves
      env = Environment()
      env.Append(BUILDERS={"CondaEnvironment": waves.scons_extensions.conda_environment()})
      environment_target = env.CondaEnvironment(target=["environment.yaml"])
      env.AlwaysBuild(environment_target)

  Parameters:

    - program – The Conda command line executable absolute or relative path

    - subcommand – The Conda environment export subcommand

    - required – A space delimited string of subcommand required arguments

    - options – A space delimited string of subcommand optional arguments

    - action_prefix – Advanced behavior. Most users should accept the defaults

  Returns:

    Conda environment builder

waves.scons_extensions.construct_action_list(

  actions: Iterable[str],
  prefix: str = '${action_prefix}',
  suffix: str = '',

) → Iterable[str]

  Return an action list with a common pre/post-fix

  Returns the constructed action list with pre/post fix strings as

      f"{prefix} {new_action} {suffix}"

  where SCons action objects are converted to their string representation. If a string is passed instead of a list, it is first converted to a list. If an empty list is passed, and empty list is returned.

  Parameters:

    - actions – List of action strings

    - prefix – Common prefix to prepend to each action

    - suffix – Common suffix to append to each action

  Returns:

    action list

waves.scons_extensions.copy_substfile(

  env: SConsEnvironment,
  source_list: list,
  substitution_dictionary: dict | None = None,
  build_subdirectory: str = '.',
  symlink: bool = False,

) → NodeList

  Pseudo-builder to copy source list to build directory and perform template substitutions on `*.in` filenames

  SCons Pseudo-Builder to chain two builders: a builder with the SCons Copy action and the SCons Substfile builders. Files are first copied to the build (variant) directory and then template substitution is performed on template files (any file ending with `*.in` suffix) to create a file without the template suffix.

  When pseudo-builders are added to the environment with the SCons AddMethod function they can be accessed with the same syntax as a normal builder. When called from the construction environment, the `env` argument is omitted. See the example below.

  To avoid dependency cycles, the source file(s) should be passed by absolute path.

  SConstruct

      import pathlib
      import waves
      current_directory = pathlib.Path(Dir(".").abspath)
      env = Environment()
      env.AddMethod(waves.scons_extensions.copy_substfile, "CopySubstfile")
      source_list = [
          "#/subdir3/file_three.ext",              # File found with respect to project root directory using SCons notation
          current_directory / file_one.ext,        # File found in current SConscript directory
          current_directory / "subdir2/file_two",  # File found below current SConscript directory
          current_directory / "file_four.ext.in"   # File with substitutions matching substitution dictionary keys
      ]
      substitution_dictionary = {
          "@variable_one@": "value_one"
      }
      env.CopySubstfile(source_list, substitution_dictionary=substitution_dictionary)

  Parameters:

    - env – An SCons construction environment to use when defining the targets.

    - source_list – List of pathlike objects or strings. Will be converted to list of pathlib.Path objects.

    - substitution_dictionary – key: value pairs for template substitution. The keys must contain the optional template characters if present, e.g. `@variable@`. The template character, e.g. `@`, can be anything that works in the SCons Substfile builder.

    - build_subdirectory – build subdirectory relative path prepended to target files

    - symlink – Whether symbolic links are created as new symbolic links. If true, symbolic links are shallow copies as a new symbolic link. If false, symbolic links are copied as a new file (dereferenced).

  Returns:

    SCons NodeList of Copy and Substfile target nodes

waves.scons_extensions.fierro_explicit_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'mpirun',
  program_required: str = '',
  program_options: str = '-np 1',
  subcommand: str = 'fierro-parallel-explicit',
  subcommand_required: str = '${SOURCE.abspath}',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Fierro explicit builder factory.

  Warning

  This is an experimental builder. It is subject to change without warning.

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  With the default options this builder requires the following sources file provided in the order:

  1. Fierro input file: `*.yaml`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && mpirun ${program_required} -np 1 fierro-parallel-explicit ${SOURCE.abspath} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["FIERRO_EXPLICIT_PROGRAM"] = env.AddProgram(["fierro-parallel-explicit"])
      env.Append(BUILDERS={
          "FierroExplicit": waves.scons_extensions.fierro_explicit_builder_factory(
              subcommand=env["FIERRO_EXPLICIT_PROGRAM"]
          )
      })
      env.FierroExplicit(
          target=["target.stdout"],
          source=["source.yaml"],
      )

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The mpirun absolute or relative path

    - program_required – Space delimited string of required mpirun options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional mpirun options and arguments that can be freely modified by the user

    - subcommand – The Fierro absolute or relative path

    - subcommand_required – Space delimited string of required Fierro options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional Fierro options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Fierro explicit builder

waves.scons_extensions.fierro_implicit_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'mpirun',
  program_required: str = '',
  program_options: str = '-np 1',
  subcommand: str = 'fierro-parallel-implicit',
  subcommand_required: str = '${SOURCE.abspath}',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Fierro implicit builder factory.

  Warning

  This is an experimental builder. It is subject to change without warning.

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  With the default options this builder requires the following sources file provided in the order:

  1. Fierro input file: `*.yaml`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && mpirun ${program_required} -np 1 fierro-parallel-implicit ${SOURCE.abspath} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["FIERRO_IMPLICIT_PROGRAM"] = env.AddProgram(["fierro-parallel-implicit"])
      env.Append(BUILDERS={
          "FierroImplicit": waves.scons_extensions.fierro_implicit_builder_factory(
              subcommand=env["FIERRO_IMPLICIT_PROGRAM"]
          )
      })
      env.FierroImplicit(
          target=["target.stdout"],
          source=["source.yaml"],
      )

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The mpirun absolute or relative path

    - program_required – Space delimited string of required mpirun options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional mpirun options and arguments that can be freely modified by the user

    - subcommand – The Fierro absolute or relative path

    - subcommand_required – Space delimited string of required Fierro options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional Fierro options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Fierro implicit builder

waves.scons_extensions.find_program(env: SConsEnvironment, names: Iterable[str]) → str

  Search for a program from a list of possible program names.

  Returns the absolute path of the first program name found. If path parts contain spaces, the part will be wrapped in double quotes.

  Example search for an executable named “program”

      import waves

      env = Environment()
      env.AddMethod(waves.scons_extensions.find_program, "FindProgram")
      env["PROGRAM"] = env.FindProgram(["program"])

  Parameters:

    - env – The SCons construction environment object to modify

    - names – list of string program names. May include an absolute path.

  Returns:

    Absolute path of the found program. None if none of the names are found.

waves.scons_extensions.first_target_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = '',
  program_required: str = '',
  program_options: str = '',
  subcommand: str = '',
  subcommand_required: str = '',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Template builder factory with WAVES default action behaviors and a task STDOUT file emitter

  This builder factory extends `waves.scons_extensions.builder_factory()` to provide a template action string with placeholder keyword arguments and WAVES builder default behavior. The default behavior will not do anything unless the `program` or `subcommand` argument is updated to include an executable program. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution. By default, SCons performs actions in the parent directory of the SConstruct file. However, many computational science and engineering programs leave output files in the current working directory, so it is convenient and sometimes necessary to change to the target’s parent directory prior to execution.

    - program – This variable is intended to containg the primary command line executable absolute or relative path

    - program_required – This variable is intended to contain a space delimited string of required program options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - program_options – This variable is intended to contain a space delimited string of optional program options and arguments that can be freely modified by the user.

    - subcommand – This variable is intended to contain the program’s subcommand. If the program variable is set to a launch controlling program, e.g. `mpirun` or `charmrun`, then the subcommand may need to contain the full target executable program and any subcommands.

    - subcommand_required – This variable is intended to contain a space delimited string of subcommand required options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – This variable is intended to contain a space delimited string of optional subcommand options and arguments that can be freely modified by the user.

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations. By default, SCons streams all STDOUT and STDERR to the terminal. However, in long or parallel workflows this may clutter the terminal and make it difficult to isolate critical debugging information, so it is convenient to redirect each program’s output to a task specific log file for later inspection and troubleshooting.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    SCons template builder

waves.scons_extensions.first_target_emitter(

  target: list,
  source: list,
  env: SConsEnvironment,
  suffixes: Iterable[str] | None = None,
  appending_suffixes: Iterable[str] | None = None,
  stdout_extension: str = '.stdout',

) → Tuple[list, list]

  SCons emitter function that emits new targets based on the first target

  Searches for a file ending in the stdout extension. If none is found, creates a target by appending the stdout extension to the first target in the `target` list. The associated Builder requires at least one target for this reason. The stdout file is always placed at the end of the returned target list.

  This is an SCons emitter function and not an emitter factory. The suffix arguments: `suffixes` and `appending_suffixes` are only relevant for developers writing new emitters which call this function as a base. The suffixes list emits targets where the suffix replaces the first target’s suffix, e.g. for `target.ext` emit a new target `target.suffix`. The appending suffixes list emits targets where the suffix appends the first target’s suffix, e.g. for `target.ext` emit a new target `target.ext.appending_suffix`.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/target.ext`. When in doubt, provide a STDOUT redirect file with the `.stdout` extension as a target, e.g. `target.stdout` or `parameter_set1/target.stdout`.

  Parameters:

    - target – The target file list of strings

    - source – The source file list of SCons.Node.FS.File objects

    - env – The builder’s SCons construction environment object

    - suffixes – Suffixes which should replace the first target’s extension

    - appending_suffixes – Suffixes which should append the first target’s extension

    - stdout_extension – The extension used by the STDOUT/STDERR redirect file

  Returns:

    target, source

waves.scons_extensions.matlab_script(

  program: str = 'matlab',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  environment_suffix: str = '> ${TARGETS[-2].abspath} 2>&1',

) → Builder

  Matlab script SCons builder

  Warning

  Experimental implementation is subject to change

  This builder requires that the Matlab script to execute is the first source in the list. The builder returned by this function accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the keyword arguments override the builder returned by this function.

  Builder/Task keyword arguments

  - `program`: The Matlab command line executable absolute or relative path

  - `matlab_options`: The Matlab command line options provided as a string.

  - `script_options`: The Matlab function interface options in Matlab syntax and provided as a string.

  - `action_prefix`: Advanced behavior. Most users should accept the defaults

  - `action_suffix`: Advanced behavior. Most users should accept the defaults.

  - `environment_suffix`: Advanced behavior. Most users should accept the defaults.

  The parent directory absolute path is added to the Matlab `path` variable prior to execution. All required Matlab files should be co-located in the same source directory.

  At least one target must be specified. The first target determines the working directory for the builder’s action, as shown in the action code snippet below. The action changes the working directory to the first target’s parent directory prior to executing the python script.

  The Builder emitter will append the builder managed targets automatically. Appends `target[0].matlab.env and ``target[0]`.stdout to the `target` list.

  The emitter will assume all emitted targets build in the current build directory. If the target(s) must be built in a build subdirectory, e.g. in a parameterized target build, then the first target must be provided with the build subdirectory, e.g. `parameter_set1/my_target.ext`. When in doubt, provide a STDOUT redirect file as a target, e.g. `target.stdout`.

  Matlab script builder action keywords

      ${action_prefix} ${program} ${matlab_options} -batch "path(path, '${SOURCE.dir.abspath}'); [fileList, productList] = matlab.codetools.requiredFilesAndProducts('${SOURCE.file}'); disp(cell2table(fileList)); disp(struct2table(productList, 'AsArray', true)); exit;" ${environment_suffix}
      ${action_prefix} ${program} ${matlab_options} -batch "path(path, '${SOURCE.dir.abspath}'); ${SOURCE.filebase}(${script_options})" ${action_suffix}

  Matlab script builder action default expansion

      cd ${TARGET.dir.abspath} && matlab ${matlab_options} -batch "path(path, '${SOURCE.dir.abspath}'); [fileList, productList] = matlab.codetools.requiredFilesAndProducts('${SOURCE.file}'); disp(cell2table(fileList)); disp(struct2table(productList, 'AsArray', true)); exit;" > ${TARGETS[-2].abspath} 2>&1
      cd ${TARGET.dir.abspath} && matlab ${matlab_options} -batch "path(path, '${SOURCE.dir.abspath}'); ${SOURCE.filebase}(${script_options})" > ${TARGETS[-1].abspath} 2>&1

  Parameters:

    - program – An absolute path or basename string for the Matlab program.

    - action_prefix – Advanced behavior. Most users should accept the defaults.

    - action_suffix – Advanced behavior. Most users should accept the defaults.

    - environment_suffix – Advanced behavior. Most users should accept the defaults.

  Returns:

    Matlab script builder

waves.scons_extensions.parameter_study_sconscript(

  env: SConsEnvironment,
  *args,
  variant_dir=None,
  exports: dict | None = None,
  study=None,
  set_name: str = '',
  subdirectories: bool = False,
  **kwargs,

)

  Wrap the SCons SConscript call to unpack parameter generators

  Always overrides the `exports` dictionary with `set_name` and `parameters` keys. When `study` is a dictionary or parameter generator, the `parameters` are overridden. When `study` is a parameter generator, the `set_name` is overridden.

  - If the study is a WAVES parameter generator object, call SConscript once per `set_name` and `parameters` in the generator’s parameter study dictionary.

  - If the study is a `dict`, call SConscript with the study as `parameters` and use the `set_name` from the method API.

  - In all other cases, the SConscript call is given the `set_name` from the method API and an empty `parameters` dictionary.

  SConstruct

      import pathlib
      import waves

      env = Environment()
      env.Append(BUILDERS={
          "AbaqusJournal": waves.scons_extensions.abaqus_journal(),
          "AbaqusSolver": waves.scons_extensions.abaqus_solver()
      })
      env.AddMethod(waves.scons_extensions.parameter_study_sconscript, "ParameterStudySConscript")

      parameter_study_file = pathlib.Path("parameter_study.h5")
      parameter_generator = waves.parameter_generators.CartesianProduct(
          {"parameter_one": [1, 2, 3]},
          output_file=parameter_study_file,
          previous_parameter_study=parameter_study_file
      )

      studies = (
          ("SConscript", parameter_generator),
          ("SConscript", {"parameter_one": 1})
      )
      for workflow, study in studies:
          env.ParameterStudySConscript(workflow, variant_dir="build", study=study, subdirectories=True)

  SConscript

      Import("env", "set_name", "parameters")

      env.AbaqusJournal(
          target=["job.inp"],
          source=["journal.py"],
          journal_options="--input=${SOURCE.abspath} --output=${TARGET.abspath} --option ${parameter_one}"
          **parameters
      )

      env.AbaqusSolver(
          target=["job.odb"],
          source=["job.inp"],
          job="job",
          **parameters
      )

  Parameters:

    - env – SCons construction environment. Do not provide when using this function as a construction environment method, e.g. `env.ParameterStudySConscript`.

    - args – All positional arguments are passed through to the SConscript call directly

    - variant_dir – The SConscript API variant directory argument

    - exports – Dictionary of `{key: value}` pairs for the `exports` variables. Must use the dictionary style because the calling script’s namespace is not available to the function namespace.

    - study – Parameter generator or dictionary simulation parameters

    - set_name – Set name to use when not provided a `study`. Overridden by the `study` set names when `study` is a parameter generator.

    - kwargs – All other keyword arguments are passed through to the SConscript call directly

    - subdirectories – Switch to use parameter generator `study` set names as subdirectories. Ignored when `study` is not a parameter generator.

  Returns:

    SConscript `Export()` variables. When called with a parameter generator study, the `Export()` variables are returned as a list with one entry per parameter set.

  Raises:

    TypeError – if `exports` is not a dictionary

waves.scons_extensions.parameter_study_task(

  env: SConsEnvironment,
  builder: Builder,
  *args,
  study=None,
  subdirectories: bool = False,
  **kwargs,

) → NodeList

  Parameter study pseudo-builder.

  SCons Pseudo-Builder aids in task construction for WAVES parameter studies with any SCons builder. Works with WAVES parameter generators or parameter dictionaries to reduce parameter study task definition boilerplate and make nominal workflow definitions directly re-usable in parameter studies.

  - If the study is a WAVES parameter generator object, loop over the parameter sets and replace `@{set_name}` in any `*args` and `**kwargs` that are strings, paths, or lists of strings and paths.

  - If the study is a `dict()`, unpack the dictionary as keyword arguments directly into the builder.

  - In all other cases, the task is passed through unchanged to the builder and the study variable is ignored.

  When chaining parameter study tasks, arguments belonging to the parameter study can be prefixed by the template `@{set_name}source.ext`. If the task uses a parameter study, the set name prefix will be replaced to match the task path modifications, e.g. `parameter_set0_source.ext` or `parameter_set0/source.ext` depending on the `subdirectories` boolean. If the task is not part of a parameter study, the set name will be removed from the source, e.g. `source.ext`. The `@` symbol is used as the delimiter to reduce with clashes in shell variable syntax and SCons substitution syntax.

  When pseudo-builders are added to the environment with the SCons AddMethod function they can be accessed with the same syntax as a normal builder. When called from the construction environment, the `env` argument is omitted.

  This pseudo-builder is most powerful when used in an SConscript call to a separate workflow configuration file. The SConscript file can then be called with a nominal parameter dictionary or with a parameter generator object. See the example below.

  SConstruct

      import pathlib
      import waves

      env = Environment()
      env.Append(BUILDERS={
          "AbaqusJournal": waves.scons_extensions.abaqus_journal(),
          "AbaqusSolver": waves.scons_extensions.abaqus_solver()
      })
      env.AddMethod(waves.scons_extensions.parameter_study_task, "ParameterStudyTask")

      parameter_study_file = pathlib.Path("parameter_study.h5")
      parameter_generator = waves.parameter_generators.CartesianProduct(
          {"parameter_one": [1, 2, 3]},
          output_file=parameter_study_file,
          previous_parameter_study=parameter_study_file
      )

      studies = (
          ("SConscript", parameter_generator),
          ("SConscript", {"parameter_one": 1})
      )
      for workflow, study in studies:
          SConscript(workflow, exports={"env": env, "study": study})

  SConscript

      Import("env", "study")

      env.ParameterStudyTask(
          env.AbaqusJournal,
          target=["@{set_name}job.inp"],
          source=["journal.py"],
          journal_options="--input=${SOURCE.abspath} --output=${TARGET.abspath} --option ${parameter_one}"
          study=study,
          subdirectories=True,
      )

      env.ParameterStudyTask(
          env.AbaqusSolver,
          target=["@{set_name}job.odb"],
          source=["@{set_name}job.inp"],
          job="job",
          study=study,
          subdirectories=True,
      )

  Parameters:

    - env – An SCons construction environment to use when defining the targets.

    - builder – The builder to parameterize

    - args – All other positional arguments are passed through to the builder after `@{set_name}` string substitutions

    - study – Parameter generator or dictionary parameter set to provide to the builder. Parameter generators are unpacked with set name directory prefixes. Dictionaries are unpacked as keyword arguments.

    - subdirectories – Switch to use parameter generator `study` set names as subdirectories. Ignored when `study` is not a parameter generator.

    - kwargs – all other keyword arguments are passed through to the builder after `@{set_name}` string substitutions

  Returns:

    SCons NodeList of target nodes

waves.scons_extensions.parameter_study_write(

  env: SConsEnvironment,
  parameter_generator,
  **kwargs,

) → NodeList

  Pseudo-builder to write a parameter generator’s parameter study file

  SConstruct

      import pathlib
      import waves

      env = Environment()
      env.AddMethod(waves.scons_extensions.parameter_study_write, "ParameterStudyWrite")

      parameter_study_file = pathlib.Path("parameter_study.h5")
      parameter_generator = waves.parameter_generators.CartesianProduct(
          {"parameter_one": [1, 2, 3]},
          output_file=parameter_study_file,
          previous_parameter_study=parameter_study_file
      )

      env.ParameterStudyWrite(parameter_generator)

  Parameters:

    - parameter_generator – WAVES ParameterGenerator class

    - kwargs – All other keyword arguments are passed directly to the `waves.parameter_generators.ParameterGenerator.write()` method.

  Returns:

    SCons NodeList of target nodes

waves.scons_extensions.print_action_signature_string(s, target, source, env) → None

  Print the action string used to calculate the action signature

  Designed to behave similarly to SCons `--debug=presub` option using `PRINT_CMD_LINE_FUNC` feature: https://scons.org/doc/production/HTML/scons-man.html#cv-PRINT_CMD_LINE_FUNC

  SConstruct

      import waves
      env = Environment(PRINT_CMD_LINE_FUNC=waves.scons_extensions.print_action_signature_string)
      env.Command(
          target=["target.txt"],
          source=["SConstruct"],
          action=["echo 'Hello World!' > ${TARGET.relpath}"]
      )

      .. code-block::
         :caption: shell

         $ scons target.txt
         scons: Reading SConscript files ...
         scons: done reading SConscript files.
         scons: Building targets ...
         Building target.txt with action signature string:
           echo 'Hello World!' > target.txt_relpath
         echo 'Hello World!' > target.txt
         scons: done building targets.

waves.scons_extensions.print_build_failures(

  env: ~SCons.Script.SConscript.SConsEnvironment = <SCons.Script.SConscript.SConsEnvironment object>,
  print_stdout: bool = True,

) → None

  On exit, query the SCons reported build failures and print the associated node’s STDOUT file, if it exists

  SConstruct

      AddOption(
          "--print-build-failures",
          dest="print_build_failures",
          default=False,
          action="store_true",
          help="Print task *.stdout target file(s) on build failures. (default: '%default')"
      )
      env = Environment(
          print_build_failures=GetOption("print_build_failures")
      )
      env.AddMethod(waves.scons_extensions.print_build_failures, "PrintBuildFailures")
      env.PrintBuildFailures(print_stdout=env["print_build_failures"])

  Parameters:

    - env – SCons construction environment

    - print_stdout – Boolean to set the exit behavior. If False, don’t modify the exit behavior.

waves.scons_extensions.project_alias(

  env: SConsEnvironment = None,
  *args,
  description: str = '',
  target_descriptions: dict = {},
  **kwargs,

) → dict

  Wrapper around the SCons Alias method. Appends and returns target descriptions dictionary.

  Parameters:

    - env – The SCons construction environment object to modify.

    - args – All other positional arguments are passed to the SCons Alias method.

    - description – String representing metadata of the alias.

    - target_descriptions – Mutable dictionary used to keep track of all alias’s metadata. If the function is called with a user-supplied dictionary, the accumulated target descriptions are reset to match the provided dictionary and all previously accumulated descriptions are discarded. If an existing alias is called it will overwrite the previous description.

    - kwargs – All other keyword arguments are passed to the SCons Alias method.

  Returns:

    target descriptions dictionary

waves.scons_extensions.project_help(

  env: ~SCons.Script.SConscript.SConsEnvironment = <SCons.Script.SConscript.SConsEnvironment object>,
  append: bool = True,
  local_only: bool = True,
  target_descriptions: dict | None = None,

) → None

  Add default targets and alias lists to project help message

  See the SCons Help documentation for appending behavior. Thin wrapper around

  - `waves.scons_extensions.project_help_default_targets()`

  - `waves.scons_extensions.project_help_aliases()`

  Parameters:

    - env – The SCons construction environment object to modify

    - append – append to the `env.Help` message (default). When False, the `env.Help` message will be overwritten if `env.Help` has not been previously called.

    - local_only – Limit help message to the project specific content when True. Only applies to SCons >=4.6.0

    - target_descriptions – dictionary containing target metadata.

waves.scons_extensions.project_help_aliases(

  env: ~SCons.Script.SConscript.SConsEnvironment = <SCons.Script.SConscript.SConsEnvironment object>,
  append: bool = True,
  local_only: bool = True,
  target_descriptions: dict | None = None,

) → None

  Add the alias list to the project’s help message

  See the SCons Help documentation for appending behavior. Adds text to the project help message formatted as

      Target Aliases:
          Alias_1
          Alias_2

  where the aliases are recovered from `SCons.Node.Alias.default_ans`.

  Parameters:

    - env – The SCons construction environment object to modify

    - append – append to the `env.Help` message (default). When False, the `env.Help` message will be overwritten if `env.Help` has not been previously called.

    - local_only – Limit help message to the project specific content when True. Only applies to SCons >=4.6.0

    - target_descriptions – dictionary containing target metadata.

waves.scons_extensions.project_help_default_targets(

  env: ~SCons.Script.SConscript.SConsEnvironment = <SCons.Script.SConscript.SConsEnvironment object>,
  append: bool = True,
  local_only: bool = True,
  target_descriptions: dict | None = None,

) → None

  Add a default targets list to the project’s help message

  See the SCons Help documentation for appending behavior. Adds text to the project help message formatted as

      Default Targets:
          Default_Target_1
          Default_Target_2

  where the targets are recovered from `SCons.Script.DEFAULT_TARGETS`.

  Parameters:

    - env – The SCons construction environment object to modify

    - append – append to the `env.Help` message (default). When False, the `env.Help` message will be overwritten if `env.Help` has not been previously called.

    - local_only – Limit help message to the project specific content when True. Only applies to SCons >=4.6.0

    - target_descriptions – dictionary containing target metadata.

waves.scons_extensions.python_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'python',
  program_required: str = '',
  program_options: str = '',
  subcommand: str = '${SOURCE.abspath}',
  subcommand_required: str = '',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Python builder factory

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  With the default options this builder requires the following sources file provided in the order:

  1. Python script: `*.py`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && python ${program_required} ${program_options} ${SOURCE.abspath} ${subcommand_required} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.Append(BUILDERS={"PythonScript": waves.scons_extensions.python_builder_factory()})
      env.PythonScript(target=["my_output.stdout"], source=["my_script.py"])

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The Python interpreter absolute or relative path

    - program_required – Space delimited string of required Python interpreter options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional Python interpreter options and arguments that can be freely modified by the user

    - subcommand – The Python script absolute or relative path

    - subcommand_required – Space delimited string of required Python script options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional Python script options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Python builder

waves.scons_extensions.quinoa_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'charmrun',
  program_required: str = '',
  program_options: str = '+p1',
  subcommand: str = 'inciter',
  subcommand_required: str = '--control ${SOURCES[0].abspath} --input ${SOURCES[1].abspath}',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Quinoa builder factory

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  With the default options this builder requires the following sources file provided in the order:

  1. Quinoa control file: `*.q`

  2. Exodus mesh file: `*.exo`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && charmrun ${program_required} +p1 inciter --control ${SOURCES[0].abspath} --input ${SOURCES[1].abspath} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = waves.scons_extensions.shell_environment("module load quinoa")
      env.Append(BUILDERS={
          "QuinoaSolver": waves.scons_extensions.quinoa_builder_factory(),
      })
      # Serial execution with "+p1"
      env.QuinoaSolver(target=["flow.stdout"], source=["flow.lua", "box.exo"])
      # Parallel execution with "+p4"
      env.QuinoaSolver(target=["flow.stdout"], source=["flow.lua", "box.exo"], program_options="+p4")

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The charmrun absolute or relative path

    - program_required – Space delimited string of required charmrun options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional charmrun options and arguments that can be freely modified by the user

    - subcommand – The inciter (quinoa executable) absolute or relative path

    - subcommand_required – Space delimited string of required inciter (quinoa executable) options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional inciter (quinoa executable) options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Quinoa builder

waves.scons_extensions.sbatch(

  program: str = 'sbatch',
  required: str = '--wait --output=${TARGETS[-1].abspath}',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',

) → Builder

  SLURM sbatch SCons builder

  The builder returned by this function accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the keyword arguments override the builder returned by this function.

  Builder/Task keyword arguments

  - `program`: The sbatch command line executable absolute or relative path

  - `required`: A space delimited string of sbatch required arguments

  - `slurm_job`: The command to submit with sbatch

  - `sbatch_options`: Optional sbatch options

  - `action_prefix`: Advanced behavior. Most users should accept the defaults

  The builder does not use a SLURM batch script. Instead, it requires the `slurm_job` variable to be defined with the command string to execute.

  At least one target must be specified. The first target determines the working directory for the builder’s action, as shown in the action code snippet below. The action changes the working directory to the first target’s parent directory prior to executing the journal file.

  The Builder emitter will append the builder managed targets automatically. Appends `target[0]`.stdout to the `target` list.

  SLURM sbatch builder action keywords

      ${action_prefix} ${program} ${required} ${sbatch_options} --wrap "${slurm_job}"

  SLURM sbatch builder action default expansion

      cd ${TARGET.dir.abspath} && sbatch --wait --output=${TARGETS[-1].abspath} ${sbatch_options} --wrap "${slurm_job}"

  SConstruct

      import waves
      env = Environment()
      env.Append(BUILDERS={"SlurmSbatch": waves.scons_extensions.sbatch()})
      env.SlurmSbatch(target=["my_output.stdout"], source=["my_source.input"], slurm_job="cat $SOURCE > $TARGET")

  Parameters:

    - program – An absolute path or basename string for the sbatch program.

    - required – A space delimited string of sbatch required arguments

    - action_prefix – Advanced behavior. Most users should accept the defaults.

  Returns:

    SLURM sbatch builder

waves.scons_extensions.sbatch_abaqus_journal(*args, **kwargs)

  Thin pass through wrapper of `waves.scons_extensions.abaqus_journal()`

  Catenate the actions and submit with SLURM sbatch. Accepts the `sbatch_options` builder keyword argument to modify sbatch behavior.

  Sbatch Abaqus journal builder action keywords

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "${action_prefix} ${program} -information environment ${environment_suffix} && ${action_prefix} ${program} ${required} ${abaqus_options} -- ${journal_options} ${action_suffix}"

  Sbatch Abaqus journal builder action default expansion

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "cd ${TARGET.dir.abspath} && abaqus cae -noGui ${SOURCE.abspath} ${abaqus_options} -- ${journal_options} > ${TARGETS[-1].abspath} 2>&1"

waves.scons_extensions.sbatch_abaqus_journal_builder_factory(*args, **kwargs)

  Thin pass through wrapper of `waves.scons_extensions.abaqus_journal_builder_factory()`

  Catenate the actions and submit with SLURM sbatch. Accepts the `sbatch_options` builder keyword argument to modify sbatch behavior.

  action string construction

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}"

waves.scons_extensions.sbatch_abaqus_solver(*args, **kwargs)

  Thin pass through wrapper of `waves.scons_extensions.abaqus_solver()`

  Catenate the actions and submit with SLURM sbatch. Accepts the `sbatch_options` builder keyword argument to modify sbatch behavior.

  Sbatch Abaqus solver builder action default expansion

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "${action_prefix} ${program} -job ${job_name} -input ${SOURCE.filebase} ${abaqus_options} ${required} ${action_suffix}"

  Sbatch Abaqus solver builder action default expansion

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "cd ${TARGET.dir.abspath} && ${program} -job ${job_name} -input ${SOURCE.filebase} ${abaqus_options} -interactive -ask_delete no > ${TARGETS[-1].abspath} 2>&1"

waves.scons_extensions.sbatch_abaqus_solver_builder_factory(*args, **kwargs)

  Thin pass through wrapper of `waves.scons_extensions.abaqus_solver_builder_factory()`

  Catenate the actions and submit with SLURM sbatch. Accepts the `sbatch_options` builder keyword argument to modify sbatch behavior.

  action string construction

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}"

waves.scons_extensions.sbatch_python_builder_factory(*args, **kwargs)

  Thin pass through wrapper of `waves.scons_extensions.python_builder_factory()`

  Catenate the actions and submit with SLURM sbatch. Accepts the `sbatch_options` builder keyword argument to modify sbatch behavior.

  action string construction

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}"

waves.scons_extensions.sbatch_quinoa_builder_factory(*args, **kwargs)

  Thin pass through wrapper of `waves.scons_extensions.quinoa_builder_factory()`

  Catenate the actions and submit with SLURM sbatch. Accepts the `sbatch_options` builder keyword argument to modify sbatch behavior.

  action string construction

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}"

waves.scons_extensions.sbatch_sierra_builder_factory(*args, **kwargs)

  Thin pass through wrapper of `waves.scons_extensions.sierra_builder_factory()`

  Catenate the actions and submit with SLURM sbatch. Accepts the `sbatch_options` builder keyword argument to modify sbatch behavior.

  action string construction

      sbatch --wait --output=${TARGET.base}.slurm.out ${sbatch_options} --wrap "${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}"

waves.scons_extensions.shell_environment(

  command: str,
  shell: str = 'bash',
  cache: str | None = None,
  overwrite_cache: bool = False,

) → SConsEnvironment

  Return an SCons shell environment from a cached file or by running a shell command

  If the environment is created successfully and a cache file is requested, the cache file is _always_ written. The `overwrite_cache` behavior forces the shell `command` execution, even when the cache file is present. If the `command` fails (raising a `subprocess.CalledProcessError`) the captured output is printed to STDERR before re-raising the exception.

  Warning

  Currently assumes a nix flavored shell: sh, bash, zsh, csh, tcsh. May work with any shell supporting command construction as below.

      {shell} -c "{command} && env -0"

  The method may fail if the command produces stdout that does not terminate in a newline. Redirect command output away from stdout if this causes problems, e.g. `command = 'command > /dev/null && command two > /dev/null'` in most shells.

  SConstruct

      import waves
      env = waves.scons_extensions.shell_environment("source my_script.sh")

  Parameters:

    - command – the shell command to execute

    - shell – the shell to use when executing command by absolute or relative path

    - cache – absolute or relative path to read/write a shell environment dictionary. Will be written as YAML formatted file regardless of extension.

    - overwrite_cache – Ignore previously cached files if they exist.

  Returns:

    SCons shell environment

  Raises:

    subprocess.CalledProcessError – Print the captured output and re-raise exception when the shell command returns a non-zero exit status.

waves.scons_extensions.sierra_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.abspath} &&',
  program: str = 'sierra',
  program_required: str = '',
  program_options: str = '',
  subcommand: str = 'adagio',
  subcommand_required: str = '-i ${SOURCE.abspath}',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Sierra builder factory

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Users overriding the `emitter` keyword argument are responsible for providing an emitter with equivalent STDOUT file handling behavior as `waves.scons_extensions.first_target_emitter()` or updating the `action_suffix` option to match their emitter’s behavior.

  With the default options this builder requires the following sources file provided in the order:

  1. Sierra input file: `*.i`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.abspath} && sierra ${program_required} ${program_options} adagio ${SOURCE.abspath} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The Sierra absolute or relative path

    - program_required – Space delimited string of required Sierra options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional Sierra options and arguments that can be freely modified by the user

    - subcommand – The Sierra application absolute or relative path

    - subcommand_required – Space delimited string of required Sierra application options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional Sierra application options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Sierra builder

waves.scons_extensions.sphinx_build(

  program: str = 'sphinx-build',
  options: str = '',
  builder: str = 'html',
  tags: str = '',

) → Builder

  Sphinx builder using the `-b` specifier

  This builder does not have an emitter. It requires at least one target.

  action

      ${program} ${options} -b ${builder} ${TARGET.dir.dir.abspath} ${TARGET.dir.abspath} ${tags}

  SConstruct

      import waves
      env = Environment()
      env.Append(BUILDERS={
          "SphinxBuild": waves.scons_extensions.sphinx_build(options="-W"),
      })
      sources = ["conf.py", "index.rst"]
      targets = ["html/index.html"]
      html = env.SphinxBuild(
          target=targets,
          source=sources,
      )
      env.Clean(html, [Dir("html")] + sources)
      env.Alias("html", html)

  Parameters:

    - program – sphinx-build executable

    - options – sphinx-build options

    - builder – builder name. See the Sphinx documentation for options

    - tags – sphinx-build tags

  Returns:

    Sphinx builder

waves.scons_extensions.sphinx_latexpdf(

  program: str = 'sphinx-build',
  options: str = '',
  builder: str = 'latexpdf',
  tags: str = '',

) → Builder

  Sphinx builder using the `-M` specifier. Intended for `latexpdf` builds.

  This builder does not have an emitter. It requires at least one target.

  action

      ${program} -M ${builder} ${TARGET.dir.dir.abspath} ${TARGET.dir.dir.abspath} ${tags} ${options}"

  SConstruct

      import waves
      env = Environment()
      env.Append(BUILDERS={
          "SphinxPDF": waves.scons_extensions.sphinx_latexpdf(options="-W"),
      })
      sources = ["conf.py", "index.rst"]
      targets = ["latex/project.pdf"]
      latexpdf = env.SphinxBuild(
          target=targets,
          source=sources,
      )
      env.Clean(latexpdf, [Dir("latex")] + sources)
      env.Alias("latexpdf", latexpdf)

  Parameters:

    - program (str) – sphinx-build executable

    - options (str) – sphinx-build options

    - builder (str) – builder name. See the Sphinx documentation for options

    - tags (str) – sphinx-build tags

  Returns:

    Sphinx latexpdf builder

waves.scons_extensions.sphinx_scanner() → Scanner

  SCons scanner that searches for directives

  - `.. include::`

  - `.. literalinclude::`

  - `.. image::`

  - `.. figure::`

  - `.. bibliography::`

  inside `.rst` and `.txt` files

  Returns:

    Sphinx source file dependency Scanner

waves.scons_extensions.ssh_builder_actions(

  builder: Builder,
  remote_server: str = '',
  remote_directory: str = '',
  rsync_push_options: str = '-rlptv',
  rsync_pull_options: str = '-rlptv',
  ssh_options: str = '',

) → Builder

  Wrap and modify a builder’s action list with remote copy operations and SSH commands

  Warning

  This builder does not provide asynchronous server-client behavior. The local/client machine must maintain the SSH connection continuously throughout the duration of the task. If the SSH connection is interrupted, the task will fail. This makes SSH wrapped builders fragile with respect to network connectivity. Users are strongly encouraged to seek solutions that allow full software installation and full workflow execution on the target compute server. If mixed server execution is required, a build directory on a shared network drive and interrupted workflow execution should be preferred over SSH wrapped builders.

  If the remote server and remote directory strings are not specified at builder instantation, then the task definitions must specify these keyword arguments. If a portion of the remote server and/or remote directory are known to be constant across all possible tasks, users may define their own substitution keyword arguments. For example, the following remote directory uses common leading path elements and introduces a new keyword variable `task_directory` to allow per-task changes to the remote directory: `remote_directory="/path/to/base/build/${task_directory}"`.

  Warning

  The `waves.scons_extensions.ssh_builder_actions()` is a work-in-progress solution with some assumptions specific to the action construction used by WAVES. It _should_ work for most basic builders, but adapting this function to users’ custom builders will probably require some advanced SCons knowledge and inspection of the `waves.scons_extensions_ssh_builder_actions()` implementation.

  Builder/Task keyword arguments

  - `remote_server`: remote server where the original builder’s actions should be executed

  - `remote_directory`: absolute or relative path where the original builder’s actions should be executed.

  - `rsync_push_options`: rsync options when pushing sources to the remote server

  - `rsync_pull_options`: rsync options when pulling remote directory from the remote server

  - `ssh_options`: SSH options when running the original builder’s actions on the remote server

  Design assumptions

  - Creates the `remote_directory` with `mkdir -p`. `mkdir` must exist on the `remote_server`.

  - Copies all source files to a flat `remote_directory` with `rsync`. `rsync` must exist on the local system.

  - Replaces instances of `cd ${TARGET.dir.abspath} &&` with `cd ${remote_directory} &&` in the original builder actions and keyword arguments.

  - Replaces instances of `SOURCE.abspath` or `SOURCES.abspath` with `SOURCE[S].file` in the original builder actions and keyword arguments.

  - Replaces instances of `SOURCES[0-9]/TARGETS[0-9].abspath` with `SOURCES[0-9]/TARGETS[0-9].file` in the original builder action and keyword arguments.

  - Prefixes all original builder actions with `cd ${remote_directory} &&`.

  - All original builder actions are wrapped in single quotes as `'{original action}'` to preserve the `&&` as part of the `remote_server` command. Shell variables, e.g. `$USER`, will not be expanded on the `remote_server`. If quotes are included in the original builder actions, they should be double quotes.

  - Returns the entire `remote_directory` to the original builder `${TARGET.dir.abspath}` with `rysnc`. `rsync` must exist on the local system.

  SConstruct

      import getpass
      import waves
      user = getpass.getuser()
      env = Environment()
      env.Append(BUILDERS={
          "SSHAbaqusSolver": waves.scons_extensions.ssh_builder_actions(
              waves.scons_extensions.abaqus_solver(
                  program="/remote/server/installation/path/of/abaqus"
              ),
              remote_server="myserver.mydomain.com",
              remote_directory="/scratch/${user}/myproject/myworkflow/${task_directory}"
          )
      })
      env.SSHAbaqusSolver(
          target=["myjob.sta"],
          source=["input.inp"],
          job_name="myjob",
          abaqus_options="-cpus 4",
          task_directory="myjob",
          user=user
      )

  my_package.py

      import SCons.Builder
      import waves

      def print_builder_actions(builder):
          for action in builder.action.list:
              print(action.cmd_list)

      def cat():
          builder = SCons.Builder.Builder(
              action=[
                  "cat ${SOURCES.abspath} | tee ${TARGETS[0].abspath}", "echo \"Hello World!\""
              ]
          )
          return builder

      build_cat = cat()

      ssh_build_cat = waves.scons_extensions.ssh_builder_actions(
          cat(), remote_server="myserver.mydomain.com", remote_directory="/scratch/roppenheimer/ssh_wrapper"
      )

      >>> import my_package
      >>> my_package.print_builder_actions(my_package.build_cat)
      cat ${SOURCES.abspath} | tee ${TARGETS[0].abspath}
      echo "Hello World!"
      >>> my_package.print_builder_actions(my_package.ssh_build_cat)
      ssh ${ssh_options} ${remote_server} "mkdir -p /scratch/roppenheimer/ssh_wrapper"
      rsync ${rsync_push_options} ${SOURCES.abspath} ${remote_server}:${remote_directory}
      ssh ${ssh_options} ${remote_server} 'cd ${remote_directory} && cat ${SOURCES.file} | tee ${TARGETS[0].file}'
      ssh ${ssh_options} ${remote_server} 'cd ${remote_directory} && echo "Hello World!"'
      rsync ${rsync_pull_options} ${remote_server}:${remote_directory} ${TARGET.dir.abspath}

  Parameters:

    - builder – The SCons builder to modify

    - remote_server – remote server where the original builder’s actions should be executed

    - remote_directory – absolute or relative path where the original builder’s actions should be executed.

    - rsync_push_options – rsync options when pushing sources to the remote server

    - rsync_pull_options – rsync options when pulling remote directory from the remote server

    - ssh_options – SSH options when running the original builder’s actions on the remote server

  Returns:

    modified builder

waves.scons_extensions.substitution_syntax(

  env: SConsEnvironment,
  substitution_dictionary: dict,
  prefix: str = '@',
  suffix: str = '@',

) → dict

  Return a dictionary copy with the pre/suffix added to the key strings

  Assumes a flat dictionary with keys of type str. Keys that aren’t strings will be converted to their string representation. Nested dictionaries can be supplied, but only the first layer keys will be modified. Dictionary values are unchanged.

  SConstruct

      env = Environment()
      env.AddMethod(waves.scons_extensions.substitution_syntax, "SubstitutionSyntax")
      original_dictionary = {"key": "value"}
      substitution_dictionary = env.SubstitutionSyntax(original_dictionary)

  Parameters:

    - substitution_dictionary (dict) – Original dictionary to copy

    - prefix (string) – String to prepend to all dictionary keys

    - suffix (string) – String to append to all dictionary keys

  Returns:

    Copy of the dictionary with key strings modified by the pre/suffix

waves.scons_extensions.truchas_builder_factory(

  environment: str = '',
  action_prefix: str = 'cd ${TARGET.dir.dir.abspath} &&',
  program: str = 'mpirun',
  program_required: str = '',
  program_options: str = '-np 1',
  subcommand: str = 'truchas',
  subcommand_required: str = '-f -o:${TARGET.dir.filebase} ${SOURCE.abspath}',
  subcommand_options: str = '',
  action_suffix: str = '> ${TARGETS[-1].abspath} 2>&1',
  emitter=<function first_target_emitter>,
  **kwargs,

) → Builder

  Truchas builder factory.

  Warning

  This is an experimental builder. It is subject to change without warning.

  Warning

  This builder is not included in the regression test suite yet. Contact the development team if you encounter problems or have recommendations for improved design behavior.

  This builder factory extends `waves.scons_extensions.first_target_builder_factory()`. This builder factory uses the `waves.scons_extensions.first_target_emitter()`. At least one task target must be specified in the task definition and the last target will always be the expected STDOUT and STDERR redirection output file, `TARGETS[-1]` ending in `*.stdout`.

  Warning

  Note that this builder’s action prefix is different from other builders. Truchas output control produces a build subdirectory, so the action prefix moves up two directories above the expected output instead of one. All Truchas output targets must include the requested output directory and the output directory name must match the target file basename, e.g. `target/target.log` and `parameter_set1/target/target.log`.

  With the default options this builder requires the following sources file provided in the order:

  1. Truchas input file: `*.inp`

  With the default options this builder requires the following target file provided in the order:

  1. Truchas output log with desired output directory: `target/target.log`

  action string construction

      ${environment} ${action_prefix} ${program} ${program_required} ${program_options} ${subcommand} ${subcommand_required} ${subcommand_options} ${action_suffix}

  action string default expansion

      ${environment} cd ${TARGET.dir.dir.abspath} && mpirun ${program_required} -np 1 truchas -f -o:${TARGET.dir.filebase} ${SOURCE.abspath} ${subcommand_options} > ${TARGETS[-1].abspath} 2>&1

  SConstruct

      import waves
      env = Environment()
      env.AddMethod(waves.scons_extensions.add_program, "AddProgram")
      env["TRUCHAS_PROGRAM"] = env.AddProgram(["truchas"])
      env.Append(BUILDERS={
          "Truchas": waves.scons_extensions.truchas_builder_factory(
              subcommand=env["TRUCHAS_PROGRAM"]
          )
      })
      env.Truchas(
          target=[
              "target/target.log"
              "target/target.h5"
          ],
          source=["source.inp"],
      )

  The builder returned by this factory accepts all SCons Builder arguments. The arguments of this function are also available as keyword arguments of the builder. When provided during task definition, the task keyword arguments override the builder keyword arguments.

  Parameters:

    - environment – This variable is intended primarily for use with builders and tasks that can not execute from an SCons construction environment. For instance, when tasks execute on a remote server with SSH wrapped actions using `waves.scons_extensions.ssh_builder_actions()` and therefore must initialize the remote environment as part of the builder action.

    - action_prefix – This variable is intended to perform directory change operations prior to program execution

    - program – The mpirun absolute or relative path

    - program_required – Space delimited string of required mpirun options and arguments that are crucial to builder behavior and should not be modified except by advanced users

    - program_options – Space delimited string of optional mpirun options and arguments that can be freely modified by the user

    - subcommand – The Truchas absolute or relative path

    - subcommand_required – Space delimited string of required Truchas options and arguments that are crucial to builder behavior and should not be modified except by advanced users.

    - subcommand_options – Space delimited string of optional Truchas options and arguments that can be freely modified by the user

    - action_suffix – This variable is intended to perform program STDOUT and STDERR redirection operations.

    - emitter – An SCons emitter function. This is not a keyword argument in the action string.

    - kwargs – Any additional keyword arguments are passed directly to the SCons builder object.

  Returns:

    Truchas builder

## Parameter Generators

External API module

Will raise `RuntimeError` or a derived class of `waves.exceptions.WAVESError` to allow the CLI implementation to convert stack-trace/exceptions into STDERR message and non-zero exit codes.

class waves.parameter_generators.CartesianProduct(

  parameter_schema: dict,
  output_file_template: str | None = None,
  output_file: str | None = None,
  output_file_type: Literal['h5', 'yaml'] = 'h5',
  set_name_template: str = 'parameter_set@number',
  previous_parameter_study: str | None = None,
  require_previous_parameter_study: bool = False,
  overwrite: bool = False,
  write_meta: bool = False,
  **kwargs,

)

  Bases: `ParameterGenerator`

  Builds a cartesian product parameter study

  Parameters must be scalar valued integers, floats, strings, or booleans

  Parameters:

    - parameter_schema – The YAML loaded parameter study schema dictionary - `{parameter_name: schema value}` CartesianProduct expects “schema value” to be an iterable. For example, when read from a YAML file “schema value” will be a Python list. Each parameter’s values must have a consistent data type, but data type may vary between parameters.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - require_previous_parameter_study – Raise a `RuntimeError` if the previous parameter study file is missing.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

  Variables:

    self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

    - waves.exceptions.SchemaValidationError –

      - Parameter schema is not a dictionary

      - Parameter key is not a supported iterable: set, tuple, list

  Example

      >>> import waves
      >>> parameter_schema = {
      ...     'parameter_1': [1, 2],
      ...     'parameter_2': ['a', 'b']
      ... }
      >>> parameter_generator = waves.parameter_generators.CartesianProduct(parameter_schema)
      >>> print(parameter_generator.parameter_study)
      <xarray.Dataset>
      Dimensions:       (set_hash: 4)
      Coordinates:
          set_hash      (set_hash) <U32 'de3cb3eaecb767ff63973820b2...
        * set_name      (set_hash) <U14 'parameter_set0' ... 'param...
      Data variables:
          parameter_1   (set_hash) object 1 1 2 2
          parameter_2   (set_hash) object 'a' 'b' 'a' 'b'

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(
    output_file_type: Literal['h5', 'yaml'] | None = None,
    dry_run: bool | None = False,
  ) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

class waves.parameter_generators.CustomStudy(

  parameter_schema: dict,
  output_file_template: str | None = None,
  output_file: str | None = None,
  output_file_type: Literal['h5', 'yaml'] = 'h5',
  set_name_template: str = 'parameter_set@number',
  previous_parameter_study: str | None = None,
  require_previous_parameter_study: bool = False,
  overwrite: bool = False,
  write_meta: bool = False,
  **kwargs,

)

  Bases: `ParameterGenerator`

  Builds a custom parameter study from user-specified values

  Parameters must be scalar valued integers, floats, strings, or booleans

  Parameters:

    - parameter_schema – Dictionary with two keys: `parameter_samples` and `parameter_names`. Parameter samples in the form of a 2D array with shape M x N, where M is the number of parameter sets and N is the number of parameters. Parameter names in the form of a 1D array with length N. When creating a parameter_samples array with mixed type (e.g. string and floats) use dtype=object to preserve the mixed types and avoid casting all values to a common type (e.g. all your floats will become strings). Each parameter’s values must have a consistent data type, but data type may vary between parameters.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - require_previous_parameter_study – Raise a `RuntimeError` if the previous parameter study file is missing.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

  Variables:

    self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

    - waves.exceptions.SchemaValidationError –

      - Parameter schema is not a dictionary

      - Parameter schema does not contain the `parameter_names` key

      - Parameter schema does not contain the `parameter_samples` key

      - The `parameter_samples` value is an improperly shaped array

  Example

      >>> import waves
      >>> import numpy
      >>> parameter_schema = dict(
      ...     parameter_samples = numpy.array([[1.0, 'a', 5], [2.0, 'b', 6]], dtype=object),
      ...     parameter_names = numpy.array(['height', 'prefix', 'index']))
      >>> parameter_generator = waves.parameter_generators.CustomStudy(parameter_schema)
      >>> print(parameter_generator.parameter_study)
      <xarray.Dataset>
      Dimensions:       (set_hash: 2)
      Coordinates:
          set_hash      (set_hash) <U32 '50ba1a2716e42f8c4fcc34a90a...
        * set_name      (set_hash) <U14 'parameter_set0' 'parameter...
      Data variables:
          height        (set_hash) object 1.0 2.0
          prefix        (set_hash) object 'a' 'b'
          index         (set_hash) object 5 6

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(output_file_type: Literal['h5', 'yaml'] | None = None, dry_run: bool | None = False) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

waves.parameter_generators.HASH_COORDINATE_KEY: Final[str] = 'set_hash'

  The set hash coordinate used in WAVES parameter study Xarray Datasets

class waves.parameter_generators.LatinHypercube(*args, **kwargs)

  Bases: `_ScipyGenerator`

  Builds a Latin-Hypercube parameter study from the scipy Latin Hypercube class

  Warning

  The merged parameter study feature does not check for consistent parameter distributions. Changing the parameter definitions and merging with a previous parameter study will result in incorrect relationships between parameter schema and the parameter study samples.

  Parameters:

    - parameter_schema – The YAML loaded parameter study schema dictionary - `{parameter_name: schema value}` LatinHypercube expects “schema value” to be a dictionary with a strict structure and several required keys. Validated on class instantiation.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - require_previous_parameter_study – Raise a `RuntimeError` if the previous parameter study file is missing.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

    - kwargs – Any additional keyword arguments are passed through to the sampler method

  Variables:

    - self.parameter_distributions – A dictionary mapping parameter names to the scipy.stats distribution

    - self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

  To produce consistent Latin Hypercubes on repeat instantiations, the `**kwargs` must include `{'seed': <int>}`. See the scipy Latin Hypercube `scipy.stats.qmc.LatinHypercube` class documentation for details The `d` keyword argument is internally managed and will be overwritten to match the number of parameters defined in the parameter schema.

  Example

      >>> import waves
      >>> parameter_schema = {
      ...     'num_simulations': 4,  # Required key. Value must be an integer.
      ...     'parameter_1': {
      ...         'distribution': 'norm',  # Required key. Value must be a valid scipy.stats
      ...         'loc': 50,               # distribution name.
      ...         'scale': 1
      ...     },
      ...     'parameter_2': {
      ...         'distribution': 'skewnorm',
      ...         'a': 4,
      ...         'loc': 30,
      ...         'scale': 2
      ...     }
      ... }
      >>> parameter_generator = waves.parameter_generators.LatinHypercube(parameter_schema)
      >>> print(parameter_generator.parameter_study)
      <xarray.Dataset>
      Dimensions:       (set_hash: 4)
      Coordinates:
          set_hash      (set_hash) <U32 '1e8219dae27faa5388328e225a...
        * set_name      (set_hash) <U14 'parameter_set0' ... 'param...
      Data variables:
          parameter_1   (set_hash) float64 0.125 ... 51.15
          parameter_2   (set_hash) float64 0.625 ... 30.97

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(
    output_file_type: Literal['h5', 'yaml'] | None = None,
    dry_run: bool | None = False,
  ) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

class waves.parameter_generators.OneAtATime(

  parameter_schema: dict,
  output_file_template: str | None = None,
  output_file: str | None = None,
  output_file_type: Literal['h5', 'yaml'] = 'h5',
  set_name_template: str = 'parameter_set@number',
  previous_parameter_study: str | None = None,
  require_previous_parameter_study: bool = False,
  overwrite: bool = False,
  write_meta: bool = False,
  **kwargs,

)

  Bases: `ParameterGenerator`

  Builds a parameter study with single-value changes from a nominal parameter set. The nominal parameter set is created from the first value of every parameter iterable.

  Parameters must be scalar valued integers, floats, strings, or booleans

  The nominal parameter set will always be the first parameter set, e.g. `parameter_set0` for the default `set_name_template`.

  Parameters:

    - parameter_schema – The YAML loaded parameter study schema dictionary - `{parameter_name: schema value}` OneAtATime expects “schema value” to be an ordered iterable. For example, when read from a YAML file “schema value” will be a Python list. Each parameter’s values must have a consistent data type, but data type may vary between parameters.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - require_previous_parameter_study – Raise a `RuntimeError` if the previous parameter study file is missing.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

  Variables:

    self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

    - waves.exceptions.SchemaValidationError –

      - Parameter schema is not a dictionary

      - Parameter key is not a supported iterable: tuple, list

      - Parameter key is empty

  Example

      >>> import waves
      >>> parameter_schema = {
      ...     'parameter_1': [1.0],
      ...     'parameter_2': ['a', 'b'],
      ...     'parameter_3': [5, 3, 7]
      ... }
      >>> parameter_generator = waves.parameter_generators.OneAtATime(parameter_schema)
      >>> print(parameter_generator.parameter_study)
      <xarray.Dataset>
      Dimensions:         (set_name: 4)
      Coordinates:
          set_hash        (set_name) <U32 '375a9b0b7c00d01bced92d9c5a6d302c' ....
        * set_name        (set_name) <U14 'parameter_set0' ... 'parameter_set3'
          parameter_sets  (set_name) <U14 'parameter_set0' ... 'parameter_set3'
      Data variables:
          parameter_1     (set_name) float64 32B 1.0 1.0 1.0 1.0
          parameter_2     (set_name) <U1 16B 'a' 'b' 'a' 'a'
          parameter_3     (set_name) int64 32B 5 5 3 7

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(output_file_type: Literal['h5', 'yaml'] | None = None, dry_run: bool | None = False) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

class waves.parameter_generators.ParameterGenerator(

  parameter_schema: dict,
  output_file_template: str | None = None,
  output_file: str | None = None,
  output_file_type: Literal['h5', 'yaml'] = 'h5',
  set_name_template: str = 'parameter_set@number',
  previous_parameter_study: str | None = None,
  require_previous_parameter_study: bool = False,
  overwrite: bool = False,
  write_meta: bool = False,
  **kwargs,

)

  Bases: `ABC`

  Abstract base class for parameter study generators

  Parameters must be scalar valued integers, floats, strings, or booleans

  Parameters:

    - parameter_schema – The YAML loaded parameter study schema dictionary, e.g. `{parameter_name: schema_value}`. Validated on class instantiation.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - require_previous_parameter_study – Raise a `RuntimeError` if the previous parameter study file is missing.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

  Variables:

    self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(
    output_file_type: Literal['h5', 'yaml'] | None = None,
    dry_run: bool | None = False,
  ) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

class waves.parameter_generators.SALibSampler(sampler_class, *args, **kwargs)

  Bases: `ParameterGenerator`, `ABC`

  Builds a SALib sampler parameter study from a SALib.sample `sampler_class`

  Samplers must use the `N` sample count argument. Note that in SALib.sample `N` is not always equivalent to the number of simulations. The following samplers are tested for parameter study shape and merge behavior:

  - fast_sampler

  - finite_diff

  - latin

  - sobol

  - morris

  Warning

  For small numbers of parameters, some SALib generators produce duplicate parameter sets. These duplicate sets are removed during parameter study generation. This may cause the SALib analyze method(s) to raise errors related to the expected parameter set count.

  Warning

  The merged parameter study feature does not check for consistent parameter distributions. Changing the parameter definitions and merging with a previous parameter study will result in incorrect relationships between parameter schema and the parameter study samples.

  Parameters:

    - sampler_class – The SALib.sample sampler class name. Case sensitive.

    - parameter_schema – The YAML loaded parameter study schema dictionary - `{parameter_name: schema value}` SALibSampler expects “schema value” to be a dictionary with a strict structure and several required keys. Validated on class instantiation.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

    - kwargs – Any additional keyword arguments are passed through to the sampler method

  Variables:

    self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

    - waves.exceptions.SchemaValidationError –

      - If the SALib sobol or SALib morris sampler is specified and there are fewer than 2 parameters.

      - `N` is not a key of `parameter_schema`

      - `problem` is not a key of `parameter_schema`

      - `names` is not a key of `parameter_schema['problem']`

      - `parameter_schema` is not a dictionary

      - `parameter_schema['N']` is not an integer

      - `parameter_schema['problem']` is not a dictionary

      - `parameter_schema['problem']['names']` is not a YAML compliant iterable (list, set, tuple)

  Keyword arguments for the SALib.sample `sampler_class` `sample` method.

  Example

      >>> import waves
      >>> parameter_schema = {
      ...     "N": 4,  # Required key. Value must be an integer.
      ...     "problem": {  # Required key. See the SALib sampler interface documentation
      ...         "num_vars": 3,
      ...         "names": ["parameter_1", "parameter_2", "parameter_3"],
      ...         "bounds": [[-1, 1], [-2, 2], [-3, 3]]
      ...     }
      ... }
      >>> parameter_generator = waves.parameter_generators.SALibSampler("sobol", parameter_schema)
      >>> print(parameter_generator.parameter_study)
      <xarray.Dataset>
      Dimensions:       (set_name: 32)
      Coordinates:
          set_hash      (set_name) <U32 'e0cb1990f9d70070eaf5638101dcaf...
        * set_name      (set_name) <U15 'parameter_set0' ... 'parameter...
      Data variables:
          parameter_1   (set_name) float64 -0.2029 ... 0.187
          parameter_2   (set_name) float64 -0.801 ... 0.6682
          parameter_3   (set_name) float64 0.4287 ... -2.871

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(output_file_type: Literal['h5', 'yaml'] | None = None, dry_run: bool | None = False) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

waves.parameter_generators.SET_COORDINATE_KEY: Final[str] = 'set_name'

  The set name coordinate used in WAVES parameter study Xarray Datasets

class waves.parameter_generators.ScipySampler(sampler_class, *args, **kwargs)

  Bases: `_ScipyGenerator`

  Builds a scipy sampler parameter study from a scipy.stats.qmc `sampler_class`

  Samplers must use the `d` parameter space dimension keyword argument. The following samplers are tested for parameter study shape and merge behavior:

  - Sobol

  - Halton

  - LatinHypercube

  - PoissonDisk

  Warning

  The merged parameter study feature does not check for consistent parameter distributions. Changing the parameter definitions and merging with a previous parameter study will result in incorrect relationships between parameter schema and the parameter study samples.

  Parameters:

    - sampler_class – The scipy.stats.qmc sampler class name. Case sensitive.

    - parameter_schema – The YAML loaded parameter study schema dictionary - `{parameter_name: schema value}` ScipySampler expects “schema value” to be a dictionary with a strict structure and several required keys. Validated on class instantiation.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

    - kwargs – Any additional keyword arguments are passed through to the sampler method

  Variables:

    - self.parameter_distributions – A dictionary mapping parameter names to the `scipy.stats` distribution

    - self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

  Keyword arguments for the `scipy.stats.qmc` `sampler_class`. The `d` keyword argument is internally managed and will be overwritten to match the number of parameters defined in the parameter schema.

  Example

      >>> import waves
      >>> parameter_schema = {
      ...     'num_simulations': 4,  # Required key. Value must be an integer.
      ...     'parameter_1': {
      ...         'distribution': 'norm',  # Required key. Value must be a valid scipy.stats
      ...         'loc': 50,               # distribution name.
      ...         'scale': 1
      ...     },
      ...     'parameter_2': {
      ...         'distribution': 'skewnorm',
      ...         'a': 4,
      ...         'loc': 30,
      ...         'scale': 2
      ...     }
      ... }
      >>> parameter_generator = waves.parameter_generators.ScipySampler("LatinHypercube", parameter_schema)
      >>> print(parameter_generator.parameter_study)
      <xarray.Dataset>
      Dimensions:       (set_hash: 4)
      Coordinates:
          set_hash      (set_hash) <U32 '1e8219dae27faa5388328e225a...
        * set_name      (set_hash) <U14 'parameter_set0' ... 'param...
      Data variables:
          parameter_1   (set_hash) float64 0.125 ... 51.15
          parameter_2   (set_hash) float64 0.625 ... 30.97

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(output_file_type: Literal['h5', 'yaml'] | None = None, dry_run: bool | None = False) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

class waves.parameter_generators.SobolSequence(*args, **kwargs)

  Bases: `_ScipyGenerator`

  Builds a Sobol sequence parameter study from the scipy Sobol class `random` method.

  Warning

  The merged parameter study feature does not check for consistent parameter distributions. Changing the parameter definitions and merging with a previous parameter study will result in incorrect relationships between parameter schema and the parameter study samples.

  Parameters:

    - parameter_schema – The YAML loaded parameter study schema dictionary - `{parameter_name: schema value}` SobolSequence expects “schema value” to be a dictionary with a strict structure and several required keys. Validated on class instantiation.

    - output_file_template – Output file name template for multiple file output of the parameter study. Required if parameter sets will be written to files instead of printed to STDOUT. May contain pathseps for an absolute or relative path template. May contain the `@number` set number placeholder in the file basename but not in the path. If the placeholder is not found it will be appended to the template string. Output files are overwritten if the content of the file has changed or if `overwrite` is True. `output_file_template` and `output_file` are mutually exclusive.

    - output_file – Output file name for single file output of the parameter study. Required if parameter sets will be written to a file instead of printed to STDOUT. May contain pathseps for an absolute or relative path. Output file is overwritten if the content of the file has changed or if `overwrite` is True. `output_file` and `output_file_template` are mutually exclusive.

    - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

    - set_name_template – Parameter set name template. Overridden by `output_file_template`, if provided.

    - previous_parameter_study – A relative or absolute file path to a previously created parameter study Xarray Dataset. If a previous parameter study exists, it is merged into the current study upon generation. Set name to content associations of the previous study are preserved when the parameter spaces between the previous and current study are identical. If the parameter spaces are unique, the current study will propagate the parameter spaces to resolve them. This will break set name to content associations of the previous study.

    - overwrite – Overwrite existing output files

    - write_meta – Write a meta file named “parameter_study_meta.txt” containing the parameter set file names. Useful for command line execution with build systems that require an explicit file list for target creation.

    - kwargs – Any additional keyword arguments are passed through to the sampler method

  Variables:

    - self.parameter_distributions – A dictionary mapping parameter names to the `scipy.stats` distribution

    - self.parameter_study – The final parameter study XArray Dataset object

  Raises:

    - waves.exceptions.MutuallyExclusiveError – If the mutually exclusive output file template and output file options are both specified

    - waves.exceptions.APIError – If an unknown output file type is requested

    - RuntimeError – If a previous parameter study file is specified and missing, and `require_previous_parameter_study` is `True`

  To produce consistent Sobol sequences on repeat instantiations, the `**kwargs` must include either `scramble=False` or `seed=<int>`. See the scipy Sobol `scipy.stats.qmc.Sobol` class documentation for details. The `d` keyword argument is internally managed and will be overwritten to match the number of parameters defined in the parameter schema.

  Example

      >>> import waves
      >>> parameter_schema = {
      ...     'num_simulations': 4,  # Required key. Value must be an integer.
      ...     'parameter_1': {
      ...         'distribution': 'uniform',  # Required key. Value must be a valid scipy.stats
      ...         'loc': 0,                   # distribution name.
      ...         'scale': 10
      ...     },
      ...     'parameter_2': {
      ...         'distribution': 'uniform',
      ...         'loc': 2,
      ...         'scale': 3
      ...     }
      ... }
      >>> parameter_generator = waves.parameter_generators.SobolSequence(parameter_schema)
      >>> print(parameter_generator.parameter_study)
      <xarray.Dataset>
      Dimensions:       (set_name: 4)
      Coordinates:
          set_hash      (set_name) <U32 'c1fa74da12c0991379d1df6541c421...
        * set_name      (set_name) <U14 'parameter_set0' ... 'parameter...
      Data variables:
          parameter_1   (set_name) float64 0.0 0.5 ... 7.5 2.5
          parameter_2   (set_name) float64 0.0 0.5 ... 4.25

  parameter_study_to_dict() → Dict[str, Dict[str, Any]]

    Return parameter study as a dictionary

    Used for iterating on parameter sets in an SCons workflow with parameter substitution dictionaries, e.g.

        >>> for set_name, parameters in parameter_generator.parameter_study_to_dict().items():
        ...     print(f"{set_name}: {parameters}")
        ...
        parameter_set0: {'parameter_1': 1, 'parameter_2': 'a'}
        parameter_set1: {'parameter_1': 1, 'parameter_2': 'b'}
        parameter_set2: {'parameter_1': 2, 'parameter_2': 'a'}
        parameter_set3: {'parameter_1': 2, 'parameter_2': 'b'}

    Returns:

      parameter study sets and samples as a dictionary: {set_name: {parameter: value}, …}

  write(output_file_type: Literal['h5', 'yaml'] | None = None, dry_run: bool | None = False) → None

    Write the parameter study to STDOUT or an output file.

    Writes to STDOUT by default. Requires non-default `output_file_template` or `output_file` specification to write to files.

    If printing to STDOUT, print all parameter sets together. If printing to files, overwrite when contents of existing files have changed. If overwrite is specified, overwrite all parameter set files. If a dry run is requested print file-content associations for files that would have been written.

    Writes parameter set files in YAML syntax by default. Output formatting is controlled by `output_file_type`.

        parameter_1: 1
        parameter_2: a

    Parameters:

      - output_file_type – Output file syntax or type. Options are: ‘yaml’, ‘h5’.

      - dry_run – Print contents of new parameter study output files to STDOUT and exit

    Raises:

      waves.exceptions.ChoicesError – If an unsupported output file type is requested

## Quantity of Interest (QOI)

Quantity of Interest (QOI) tools

Warning

This module is considered experimental pending early adopter end user trial and feedback.

The QOI xarray data array and dataset handling of `create_qoi()` and `create_qoi_set()` should be stable, but the output plotting and reporting formatting is subject to change.

waves.qoi.create_qoi(

  name: str,
  calculated: float = nan,
  expected: float = nan,
  lower_rtol: float = nan,
  upper_rtol: float = nan,
  lower_atol: float = nan,
  upper_atol: float = nan,
  lower_limit: float = nan,
  upper_limit: float = nan,
  **attrs,

) → DataArray

  Create a QOI DataArray.

  If you create a QOI with calculated values, and a separate QOI with only expected values, you can combine them with `xarray.merge([calculated, expected])`.

  Parameters:

    - name – QOI name

    - expected (calculated,) – Calculated and expected QOI values, respectively.

    - upper_limit (lower_rtol, lower_atol, lower_limit, upper_rtol, upper_atol,) – Tolerance values which set the acceptable range of calculated QOI values. Any or all of these tolerances may be specified. If `lower_rtol` or `upper_rtol` are specified, `expected` must also be specified. The calculated QOI value will be considered within tolerance if it is greater than or equal to `max((lower_limit, expected + lower_atol, expected + abs(expected * lower_rtol))` and less than or equal to `min((upper_limit, expected + upper_atol, expected + abs(expected * upper_rtol))`. Unspecified tolerances are not considered in the tolerance check. If no tolerances are specified, the calculated QOI will always be considered within tolerance.

    - attrs – Attributes to associate with the QOI. Recommended attributes are: group, units, description, long_name, version. Together `name` and `attrs['group']` should distinguish each QOI from every other QOI in the Mod/Sim repository. In other words, `group` should be as specific as possible, e.g., “Local Test XYZ Assembly Preload” instead of just “Preload”.

  Returns:

    QOI

  Example

      >>> load = waves.qoi.create_qoi(
      ...     name="load",
      ...     calculated=5.0,
      ...     units="N",
      ...     long_name="Axial Load",
      ...     description="Axial load through component XYZ",
      ...     group="Assembly ABC Preload",
      ...     version="abcdef",
      ...     date="2025-01-01",
      ... )
      >>> load
      <xarray.DataArray 'load' (value_type: 4)> Size: 32B
      array([ 5., nan, nan, nan])
      Coordinates:
        * value_type  (value_type) <U11 176B 'calculated' 'expected' ... 'upper_limit'
      Attributes:
          units:        N
          long_name:    Axial Load
          description:  Axial load through component XYZ
          group:        Assembly ABC Preload
          version:      abcdef
          date:         2025-01-01

waves.qoi.create_qoi_set(qois: Iterable[DataArray]) → Dataset

  Create a QOI dataset containing multiple QOIs from a single simulation.

  This operation combines multiple QOIs (`xarray.DataArray``s) into a single "QOI Set" (``xarray.Dataset`) using `xarray.merge()`. This results in an `xarray.Dataset` with each QOI represented as a separate data variable. Each QOI must have a unique name. If multiple QOIs share a dimension name then that dimension will be merged across QOIs. This can lead to sparse Datasets if the dimension’s index values differ. To avoid this, use unique dimension names or avoid combining those QOIs into the same QOI set. No attributes will be set at the top-level Dataset, but QOI attributes will be preserved at the data variable level.

  Parameters:

    qois – Sequence of QOIs.

  Returns:

    QOI Set containing each QOI as a separate data variable.

  Example

      >>> load = waves.qoi.create_qoi(
      ...     name="load",
      ...     calculated=5.0,
      ...     units="N",
      ...     long_name="Axial Load",
      ...     description="Axial load through component XYZ",
      ...     group="Assembly ABC Preload",
      ...     version="abcdef",
      ...     date="2025-01-01",
      ... )
      ... gap = waves.qoi.create_qoi(
      ...     name="gap",
      ...     calculated=1.0,
      ...     units="mm",
      ...     long_name="Radial gap",
      ...     description="Radial gap between components A and B",
      ...     group="Assembly ABC Preload",
      ...     version="abcdef",
      ...     date="2025-01-01",
      ... )
      ...
      ... # Combine QOIs into calculated QOIs set
      ... simulation_1_qois = waves.qoi.create_qoi_set((load, gap))
      ... simulation_1_qois
      <xarray.Dataset> Size: 240B
      Dimensions:     (value_type: 4)
      Coordinates:
        * value_type  (value_type) <U11 176B 'calculated' 'expected' ... 'upper_limit'
      Data variables:
          load        (value_type) float64 32B 5.0 nan nan nan
          gap         (value_type) float64 32B 1.0 nan nan nan
      >>> simulation_1_qois["load"]
      <xarray.DataArray 'load' (value_type: 4)> Size: 32B
      array([ 5., nan, nan, nan])
      Coordinates:
        * value_type  (value_type) <U11 176B 'calculated' 'expected' ... 'upper_limit'
      Attributes:
          units:        N
          long_name:    Axial Load
          description:  Axial load through component XYZ
          group:        Assembly ABC Preload
          version:      abcdef
          date:         2025-01-01

waves.qoi.write_qoi_set_to_csv(qoi_set: Dataset, output: Path) → None

  Writes a QOI Dataset to a CSV file.

  Parameters:

    - qoi_set – QOI set.

    - output – Output CSV file.

  Example

      >>> simulation_1_qois
      <xarray.Dataset> Size: 240B
      Dimensions:     (value_type: 4)
      Coordinates:
        * value_type  (value_type) <U11 176B 'calculated' 'expected' ... 'upper_limit'
      Data variables:
          load        (value_type) float64 32B 5.0 4.5 3.5 5.5
          gap         (value_type) float64 32B 1.0 0.8 0.7 0.9
      >>> waves.qoi.write_qoi_set_to_csv(simulation_1_qois, "simulation_1_qois.csv")

  name | calculated | expected | lower_limit | upper_limit | units | long_name | description | group | version | date
  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
  load | 5.0 | 4.5 | 3.5 | 5.5 | N | Axial Load | Axial load through component XYZ | Assembly ABC Preload | abcdef | 2025-01-01
  gap | 1.0 | 0.8 | 0.7000000000000001 | 0.9 | mm | Radial gap | Radial gap between components A and B | Assembly ABC Preload | abcdef | 2025-01-01

## Exceptions

Module of package specific exceptions.

The project design intent is to print error messages to STDERR and return non-zero exit codes when used as a command line utility (CLI), but raise exceptions when used as a package (API). The only time a stack trace should be printed when using the CLI is if the exception is unexpected and may represent an internal bug.

Most raised exceptions in the package API should be Python built-ins. However, to support the CLI error handling described above some exceptions need to be uniquely identifiable as package exceptions and not third-party exceptions. `waves.exceptions.WAVESError()` and `RuntimeError` exceptions will be be caught by the command line utility and converted to error messages and non-zero return codes. Third-party exceptions represent truly unexpected behavior that may be an internal bug and print a stack trace.

This behavior could be supported by limiting package raised exceptions to RuntimeError exceptions; however, more specific exceptions are desirable when using the package API to allow end-users to handle different collections of API exceptions differently.

exception waves.exceptions.APIError

  Bases: `WAVESError`

  Raised when an API validation fails, e.g. an argument value is outside the list of acceptable choices. Intended to mirror an associated `argparse` CLI option validation.

exception waves.exceptions.ChoicesError

  Bases: `APIError`

  Raised during API validation that mirrors an `argparse` CLI argument with limited choices.

exception waves.exceptions.MutuallyExclusiveError

  Bases: `APIError`

  Raised during API validation that mirrors an `argparse` CLI mutually exclusive group.

exception waves.exceptions.SchemaValidationError

  Bases: `APIError`

  Raised when a WAVES parameter generator schema validation fails

exception waves.exceptions.WAVESError

  Bases: `Exception`

  The base class for WAVES exceptions. All exceptions that must be caught by the CLI should derive from this class.