Mondaic Documentation
www.mondaic.com
Mondaic
Version:
No results found.
python_api
/
salvus
/
flow
/
functions

salvus.flow.functions

salvus.flow.functions salvus flow functions
Various functions to interact with SalvusFlow in a more direct way.

Functions

add_job_group()

Add a new job group to the database.
SIGNATURE
def add_job_group(
    name: str, description: str, info: dict | None = None
) -> None: ...
ARGUMENTS
Required
name
Type:str
Description:
Name of the job group.
Required
description
Type:str
Description:
Description of the job group.
Optional
info
Type:dict | None
Default value:None
Description:
Optional info dictionary.

cancel_all_running_jobs()

Cancel all running or pending jobs for a given site.
SIGNATURE
def cancel_all_running_jobs(site_name: str, verbosity: int = 1) -> None: ...
ARGUMENTS
Required
site_name
Type:str
Description:
Name of the site which's jobs to cancel.
Optional
verbosity
Type:int
Default value:1
Description:
Verbosity level.

get_all_job_groups()

Get all job groups from the database.
SIGNATURE
def get_all_job_groups(
    include_job_count: bool = False,
) -> list[db.JobGroup]: ...
ARGUMENTS
Optional
include_job_count
Type:bool
Default value:False
Description:
Count the jobs for each group. Potentially somewhat slow.
RETURNS
Return type: list[db.JobGroup]
List of all job groups.

get_job()

Get a SalvusJob object by querying the database.
SIGNATURE
def get_job(site_name: str, job_name: str) -> SalvusJob: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The site this job is on.
Required
job_name
Type:str
Description:
The name of the job.
RETURNS
Return type: SalvusJob
The queried for job.

get_job_array()

Get a SalvusJobArray object.
SIGNATURE
def get_job_array(site_name: str, job_array_name: str) -> SalvusJobArray: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The site this job array is on.
Required
job_array_name
Type:str
Description:
The name of the job array.
RETURNS
Return type: SalvusJobArray
The queried for job array.

get_job_arrays()

Query for a list of SalvusJobArray objects.
SIGNATURE
def get_job_arrays(
    limit: salvus._core.types.int_ = 100,
    site_name: str | None = None,
    job_array_status: list[JobStatus | str] | None = None,
    order_by: Iterable[str] = ("last_updated", "desc"),
    update_job_arrays: bool = False,
) -> list[SalvusJobArray]: ...
ARGUMENTS
Optional
limit
Type:salvus._core.types.int_
Default value:100
Description:
Maximum number of returned job arrays.
Optional
site_name
Type:str | None
Default value:None
Description:
Only return job arrays from this site.
Optional
job_array_status
Type:list[JobStatus | str] | None
Default value:None
Description:
Limit returned jobs to job arrays with these statuses. Will return any job if not given.
Optional
order_by
Type:Iterable[str]
Default value:('last_updated', 'desc')
Description:
Choose how to order by (database column, direction). Available database columns are "last_updated", "job_array_start_time", "job_array_end_time", and "status".
Optional
update_job_arrays
Type:bool
Default value:False
Description:
Update pending/running job arrays.
RETURNS
Return type: list[SalvusJobArray]
List of job arrays satisfying the query criteria.

get_jobs()

Query for a list of SalvusJob objects.
SIGNATURE
def get_jobs(
    limit: salvus._core.types.int_ = 100,
    site_name: str | None = None,
    job_status: list[JobStatus | str] | JobStatus | None = None,
    order_by: Iterable[str] = ("last_updated", "desc"),
    update_jobs: bool = False,
    skip_jobs_from_job_arrays: bool = True,
) -> list[SalvusJob]: ...
ARGUMENTS
Optional
limit
Type:salvus._core.types.int_
Default value:100
Description:
Maximum number of returned jobs.
Optional
site_name
Type:str | None
Default value:None
Description:
Only return jobs from this site.
Optional
job_status
Type:list[JobStatus | str] | JobStatus | None
Default value:None
Description:
Limit returned jobs to jobs with these statuses. Will return jobs job if not given.
Optional
order_by
Type:Iterable[str]
Default value:('last_updated', 'desc')
Description:
Choose how to order by (database column, direction). Available database columns are "last_updated", "job_start_time", "job_end_time", and "status".
Optional
update_jobs
Type:bool
Default value:False
Description:
Update pending/running jobs.
Optional
skip_jobs_from_job_arrays
Type:bool
Default value:True
Description:
Don't return jobs that are part of a job array.
RETURNS
Return type: list[SalvusJob]
List of jobs satisfying the query criteria.

get_site()

Get an initialized site object from the chose site.
SIGNATURE
def get_site(
    site_name: str,
    verbosity: salvus._core.types.int_ = 1,
    skip_version_number_check: bool = False,
) -> executors.BaseExecutor: ...
ARGUMENTS
Required
site_name
Type:str
Description:
Name of the remote executor.
Optional
verbosity
Type:salvus._core.types.int_
Default value:1
Description:
Verbosity level.
Optional
skip_version_number_check
Type:bool
Default value:False
Description:
Skip the version number check of the local Python version vs the remote site. Useful for initializing and updating sites.
RETURNS
Return type: executors.BaseExecutor
The requested, initialized site.

get_task_chain()

Get a TaskChain object by querying the database.
SIGNATURE
def get_task_chain(site_name: str, job_name: str) -> TaskChain: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The site this job is on.
Required
job_name
Type:str
Description:
The name of the job of the task chain.
RETURNS
Return type: TaskChain
The queried for task chain.

initialize_site()

Initialize a site using information from the config TOML file.
SIGNATURE
def initialize_site(
    site_name: str,
    verbosity: int = 1,
    wait_for_initial_run_in_seconds: salvus._core.types.float_ = 3.0,
) -> executors.BaseExecutor: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The name of the site.
Optional
verbosity
Type:int
Default value:1
Description:
Verbosity level.
Optional
wait_for_initial_run_in_seconds
Type:salvus._core.types.float_
Default value:3.0
Description:
How long to wait for the job to finish before querying for the first time. 3 seconds is a good number for most cases, for testing this can be shortened.
RETURNS
Return type: executors.BaseExecutor

run()

Run one Salvus simulation and block until it is done.
Will run the simulation, wait for it to be done, download all output files, and finally delete all remote files and the job's entry in the Salvus internal database.
SIGNATURE
def run(
    site_name: str,
    input_file: str | pathlib.Path | dict | _DeepSetter,
    output_folder: str | pathlib.Path,
    ranks: salvus._core.types.int_ | None = None,
    wall_time_in_seconds: salvus._core.types.float_ | None = None,
    ping_interval_in_seconds: salvus._core.types.float_ | None = None,
    job_groups: list[str] | None = None,
    job_name: str | None = None,
    get_all: bool = False,
    overwrite: bool = False,
    delete_remote_files: bool = True,
    raise_on_deletion_failure: bool = False,
    verbosity: int = 1,
) -> SalvusJob: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The remote executor to use.
Required
input_file
Type:str | pathlib.Path | dict | _DeepSetter
Description:
The input file or simulation object for the run.
Required
output_folder
Type:str | pathlib.Path
Description:
Output files will be copied here.
Optional
ranks
Type:salvus._core.types.int_ | None
Default value:None
Description:
The number of ranks to run with. Defaults to the site's configuration value.
Optional
wall_time_in_seconds
Type:salvus._core.types.float_ | None
Default value:None
Description:
The wall time in seconds if the site requires one.
Optional
ping_interval_in_seconds
Type:salvus._core.types.float_ | None
Default value:None
Description:
How often to query the remote site about the job status. Defaults to the site's configuration value.
Optional
job_groups
Type:list[str] | None
Default value:None
Description:
Job groups to attach to the job in the database.
Optional
job_name
Type:str | None
Default value:None
Description:
Custom job name. Be careful with this.
Optional
get_all
Type:bool
Default value:False
Description:
Get all output files. Wavefield outputs are omitted by default.
Optional
overwrite
Type:bool
Default value:False
Description:
Delete the output folder before running if it already exists.
Optional
delete_remote_files
Type:bool
Default value:True
Description:
Delete remote files after the run has finished.
Optional
raise_on_deletion_failure
Type:bool
Default value:False
Description:
If True this function will raise if, after everything ran, there is an error in the cleanup stage. This can happen for example on networked file systems.
Optional
verbosity
Type:int
Default value:1
Description:
The verbosity level.
EXCEPTIONS
ValueError
Raised if the output folder already exists and overwrite is False.
RETURNS
Return type: SalvusJob
The salvus.flow.executors.salvus_job.SalvusJob object representing the job.

run_async()

Launch one Salvus simulation asynchronously.
This function will return immediately upon successful submission of the job.
SIGNATURE
def run_async(
    site_name: str,
    input_file: str | pathlib.Path | dict | _DeepSetter,
    ranks: salvus._core.types.int_ | None = None,
    wall_time_in_seconds: salvus._core.types.float_ | None = None,
    job_groups: list[str] | None = None,
    job_name: str | None = None,
    verbosity: salvus._core.types.int_ = 1,
) -> SalvusJob: ...
ARGUMENTS
Required
site_name
Type:str
Description:
Name of the remote executor.
Required
input_file
Type:str | pathlib.Path | dict | _DeepSetter
Description:
The input file or simulation object for the run.
Optional
ranks
Type:salvus._core.types.int_ | None
Default value:None
Description:
The number of ranks to run with. Defaults to the site's configuration value.
Optional
wall_time_in_seconds
Type:salvus._core.types.float_ | None
Default value:None
Description:
The wall time in seconds if the site requires one.
Optional
job_groups
Type:list[str] | None
Default value:None
Description:
Job groups to attach to the job in the database.
Optional
job_name
Type:str | None
Default value:None
Description:
Custom job name. Be careful with this.
Optional
verbosity
Type:salvus._core.types.int_
Default value:1
Description:
The verbosity level.
RETURNS
Return type: SalvusJob
The salvus.flow.executors.salvus_job.SalvusJob object representing the just submitted job.

run_many()

Run many Salvus simulations and block until they are done.
Will run the simulations, wait them to be done, download all output files, and finally delete all remote files as well as the jobs' entry in the Salvus internal database.
SIGNATURE
def run_many(
    site_name: str,
    input_files: Iterable[str | pathlib.Path | dict | _DeepSetter],
    output_folder: str | pathlib.Path,
    ranks_per_job: salvus._core.types.int_ | None = None,
    wall_time_in_seconds_per_job: salvus._core.types.float_ | None = None,
    ping_interval_in_seconds: salvus._core.types.float_ | None = None,
    get_all: bool = False,
    overwrite: bool = False,
    copy_partial_results: bool = True,
    delete_remote_files: bool = True,
    raise_on_deletion_failure: bool = False,
    verbosity: int = 1,
) -> SalvusJobArray: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The remote executor to use.
Required
input_files
Type:Iterable[str | pathlib.Path | dict | _DeepSetter]
Description:
A list of input files or simulation objects to be run.
Required
output_folder
Type:str | pathlib.Path
Description:
Output files will be copied here.
Optional
ranks_per_job
Type:salvus._core.types.int_ | None
Default value:None
Description:
The number of ranks to run each job with. Defaults to the site's configuration value.
Optional
wall_time_in_seconds_per_job
Type:salvus._core.types.float_ | None
Default value:None
Description:
The wall time in seconds per job if the site requires one.
Optional
ping_interval_in_seconds
Type:salvus._core.types.float_ | None
Default value:None
Description:
How often to query the remote site about the jobs' status. Defaults to the site's configuration value.
Optional
get_all
Type:bool
Default value:False
Description:
Get all output files. Wavefield outputs are omitted by default.
Optional
overwrite
Type:bool
Default value:False
Description:
Delete the output folder before running if it already exists.
Optional
copy_partial_results
Type:bool
Default value:True
Description:
If this is True (the default) partial results will be copied over. This means that as long as a few jobs in the job array succeeded, these will be copied over. The function will still raise an exception but the data will be copied. Otherwise it will just raise.
Optional
delete_remote_files
Type:bool
Default value:True
Description:
Delete remote files after the run has finished.
Optional
raise_on_deletion_failure
Type:bool
Default value:False
Description:
If True this function will raise if, after everything ran, there is an error in the cleanup stage. This can happen for example on networked file systems.
Optional
verbosity
Type:int
Default value:1
Description:
The verbosity level.
EXCEPTIONS
ValueError
Raised if the output folder already exists.
RETURNS
Return type: SalvusJobArray

run_many_async()

Launch many Salvus simulations asynchronously.
This function will return immediately upon successful submission of the jobs.
SIGNATURE
def run_many_async(
    site_name: str,
    input_files: Iterable[str | pathlib.Path | dict | _DeepSetter],
    ranks_per_job: salvus._core.types.int_ | None = None,
    wall_time_in_seconds_per_job: salvus._core.types.float_ | None = None,
    job_groups: list[str] | None = None,
    verbosity: salvus._core.types.int_ = 1,
) -> SalvusJobArray: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The remote executor to use.
Required
input_files
Type:Iterable[str | pathlib.Path | dict | _DeepSetter]
Description:
A list of input files or simulation objects to be run.
Optional
ranks_per_job
Type:salvus._core.types.int_ | None
Default value:None
Description:
The number of ranks to run each job with. Defaults to the site's configuration value.
Optional
wall_time_in_seconds_per_job
Type:salvus._core.types.float_ | None
Default value:None
Description:
The wall time in seconds per job if the site requires one.
Optional
job_groups
Type:list[str] | None
Default value:None
Description:
Job groups to attach to the job in the database.
Optional
verbosity
Type:salvus._core.types.int_
Default value:1
Description:
The verbosity level.
RETURNS
Return type: SalvusJobArray
The SalvusJobArray object representing the just submitted job array.

run_task_chain()

Launch a new task chain and wait for it to finish.
Contrary to the run() and run_many() functions this does not automatically download the results and cleans up all remote files. This still has to be done manually. The reasons for this is that task chains usually execute more complicated things and only some outputs are, in the end, required.
SIGNATURE
def run_task_chain(
    site_name: str,
    tasks: list[_DeepSetter | typing.Callable],
    ranks: salvus._core.types.int_,
    wall_time_in_seconds: salvus._core.types.float_ | None = None,
    data_files_to_upload: list[pathlib.Path | str] | None = None,
    ping_interval_in_seconds: salvus._core.types.float_ | None = None,
    job_name: str | None = None,
    verbosity: int = 1,
    interactive_tty: bool = False,
) -> TaskChain: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The remote executor to use.
Required
tasks
Type:list[_DeepSetter | typing.Callable]
Description:
A list of tasks. Each task can either be a Salvus simulation or a Python function.
Required
ranks
Type:salvus._core.types.int_
Description:
The number of ranks to run with. Will only affect the Salvus runs.
Optional
wall_time_in_seconds
Type:salvus._core.types.float_ | None
Default value:None
Description:
The wall time in seconds if the site requires one.
Optional
data_files_to_upload
Type:list[pathlib.Path | str] | None
Default value:None
Description:
List of optional data files to upload to the task chain directory.
Optional
ping_interval_in_seconds
Type:salvus._core.types.float_ | None
Default value:None
Description:
How often to query the remote site about the job status. Defaults to the site's configuration value.
Optional
job_name
Type:str | None
Default value:None
Description:
Name of the task chain job.
Optional
verbosity
Type:int
Default value:1
Description:
The verbosity level.
Optional
interactive_tty
Type:bool
Default value:False
Description:
Flag for interactive tty.
RETURNS
Return type: TaskChain

run_task_chain_async()

Launch a new task chain and return it.
SIGNATURE
def run_task_chain_async(
    site_name: str,
    tasks: list[_DeepSetter | typing.Callable],
    ranks: salvus._core.types.int_,
    wall_time_in_seconds: salvus._core.types.float_ | None = None,
    data_files_to_upload: None | list[pathlib.Path | str] = None,
    job_name: str | None = None,
    verbosity: int = 1,
    interactive_tty: bool = False,
) -> TaskChain: ...
ARGUMENTS
Required
site_name
Type:str
Description:
The remote executor to use.
Required
tasks
Type:list[_DeepSetter | typing.Callable]
Description:
A list of tasks. Each task can either be a Salvus simulation or a Python function.
Required
ranks
Type:salvus._core.types.int_
Description:
The number of ranks to run with. Will only affect the Salvus runs.
Optional
wall_time_in_seconds
Type:salvus._core.types.float_ | None
Default value:None
Description:
The wall time in seconds if the site requires one.
Optional
data_files_to_upload
Type:None | list[pathlib.Path | str]
Default value:None
Description:
List of optional data files to upload to the task chain directory.
Optional
job_name
Type:str | None
Default value:None
Description:
Name of the task chain job.
Optional
verbosity
Type:int
Default value:1
Description:
The verbosity level.
Optional
interactive_tty
Type:bool
Default value:False
Description:
Flag for interactive tty.
RETURNS
Return type: TaskChain

set_config()

Set the configuration for all API calls in this Python session.
SIGNATURE
def set_config(site_settings: pathlib.Path | dict, db_path: str) -> None: ...
ARGUMENTS
Required
site_settings
Type:pathlib.Path | dict
Description:
Filename or existing dictionary with the site settings.
Required
db_path
Type:str
Description:
Path to the sqlite database used to internally keep track of things.

set_default_config()

Reset the configuration for all API calls to the defaults.
SIGNATURE
def set_default_config() -> None: ...

temporary_salvus_config()

Context manager creating a temporary SalvusFlow context.
No sites and nothing will be inherited from the global setting in that context and the database will life in memory and only exist for the duration of the context manager.
SIGNATURE
def temporary_salvus_config() -> typing.Generator[None, None, None]: ...
RETURNS
Return type: typing.Generator[None, None, None]

Classes

add_new_executor

Add a new site/executor to Salvus.
This is an alternative to the usual way of adding a site/executor via add salvus-cli add-site and salvus-flow init-site. This function will not test the configuration but just assume that it works. The new site/executor will be immediately available for use.
SIGNATURE
class add_new_executor(builtins.object):
    def __init__(
        self,
        site_name: str,
        executor_type: str,
        salvus_binary: pathlib.Path | str,
        salvus_floating_point_size: typing.Literal[32, 64] = 32,
        run_directory: pathlib.Path | str,
        tmp_directory: pathlib.Path | str,
        use_cuda_capable_gpus: bool,
        default_ranks: int,
        max_ranks: int,
        ssh_settings: dict[str, str] | None = None,
        environment_variables: dict[str, str] | None = None,
        site_specific: dict[str, typing.Any] | None = None,
        verbosity: int = 1,
        overwrite: bool = False,
    ): ...
ARGUMENTS
Required
site_name
Type:str
Description:
The name of the site.
Required
executor_type
Type:str
Description:
The type of executor. Can be "local", "ssh", or one of the other supported types.
Required
salvus_binary
Type:pathlib.Path | str
Description:
Path to the Salvus binary.
Optional
salvus_floating_point_size
Type:typing.Literal[32, 64]
Default value:32
Description:
The floating point size of the Salvus binary in bit. Either 32 or 64. No check if performed if this is correct.
Required
run_directory
Type:pathlib.Path | str
Description:
The run directory of Salvus.
Required
tmp_directory
Type:pathlib.Path | str
Description:
The temp directory of Salvus.
Required
use_cuda_capable_gpus
Type:bool
Description:
Whether to use GPUs or not.
Required
default_ranks
Type:int
Description:
The default number of ranks to use.
Required
max_ranks
Type:int
Description:
The maximum number of ranks to use.
Optional
ssh_settings
Type:dict[str, str] | None
Default value:None
Description:
SSH settings if the executor requires communication over SSH.
Optional
environment_variables
Type:dict[str, str] | None
Default value:None
Description:
Environment variables for the new executor.
Optional
site_specific
Type:dict[str, typing.Any] | None
Default value:None
Description:
Site specific settings.
Optional
verbosity
Type:int
Default value:1
Description:
The verbosity level.
Optional
overwrite
Type:bool
Default value:False
Description:
Overwrite the site if it already exists.

Used in tutorials

Functionality from this module is used in the following tutorials.
Advanced Interface / Manual Gradients / Manual Gradient Computation
Advanced Interface / Salvus Flow Api / Introduction to SalvusFlow's API
Examples / Applications / Ndt / Cone Pitting / Conical Pitting
Examples / Applications / Ndt / Defects / Ultrasonic Weld Inspection Tutorial
Examples / Applications / Ndt / Maximum Amplitude Distributions / Maximum Amplitude Distributions
Examples / Applications / Ndt / Notches / Notched Specimens
Examples / Integration Tests / Analytic Tests / Diffusion Equation / Benchmark: Diffusion equation
Examples / Integration Tests / Analytic Tests / Poisson Equation / Benchmark: Poisson's equation
Inversion / Smoothing / Diffusion Equation
Models And Topo / Model Order / Model Interpolation
Models And Topo / Parameterizations / Model Parameterizations in Salvus
Previous
types
Next
simple_config
We use cookies to analyze our traffic, but won't track you until explicit consent is given. Using our contact form will create relevant cookies and transmit data to third party services to keep track of your request. Read more about how we use personal information in our Privacy Policy.
PAGE CONTENTS