PARyOpt.evaluators package

Submodules

PARyOpt.evaluators.async module

class PARyOpt.evaluators.async.AsyncFunctionEvaluator(required_fraction: float = 1.0, max_pending: int = 0)[source]

Bases: object

Abstract base class for long-running cost functions (e.g. external simulations). Must be subclassed. Subclasses should fill in start() and check_for_results(). Automatically saves state as jobs are submitted.

check_for_result(x: <built-in function array>, data: Any) → Union[PARyOpt.evaluators.async.ValueNotReady, PARyOpt.evaluators.async.EvaluationFailed, PARyOpt.evaluators.async.EvaluateAgain, float][source]

Returns the cost function evaluation at x, if the value is available. This method is only called after start.

Parameters:
  • x – the point to evaluate the cost function at
  • data – user data returned by start(x)
Returns:

an instance of ValueNotReady if such, EvaluationFailed(reason), or the cost function value at x (float)

evaluate_population(xs: List[<built-in function array>], if_ready_xs: List[<built-in function array>] = []) → Tuple[List[Tuple[<built-in function array>, float]], List[<built-in function array>], List[<built-in function array>]][source]

Evaluates a population of x values, encoded as a list of 1D numpy arrays. Returns a tuple containing three lists:

  • Completed values: [ (x1, y1), (x2, y2), … ]
  • Pending values - evaluation is in progress, but not complete: [ x1, x2, … ]
  • Failed values - evaluation completed unsuccessfully: [ x1, x2, … ]

The union of completed, failed, and pending is equal to the union of xs and if_ready_xs. The __init__ parameter required_fraction tunes how many completed/pending values are returned.

Parameters:
  • xs – list of new points to check
  • if_ready_xs – List of points to include in the return tuple if they available by the time we evaluate the minimum required percentage of xs. These points do not count towards the minimum required completed points.
Returns:

( [(x, y), …] completed, [x, …] pending, [x, …] failed )

start(x: <built-in function array>) → Any[source]

Start a cost function evaluation at the given x location. This method may return anything - the data will be passed on to check_for_result(). The only restriction is that the return value should be pickle-able to enable restart support.

Parameters:x – point to begin evaluation at
Returns:user data that will be fed into check_for_result()
class PARyOpt.evaluators.async.EvaluateAgain(reason: str)[source]

Bases: object

Indicates evaluation needs to be done again, due to some reason (for eg., during hardware failures)

class PARyOpt.evaluators.async.EvaluationFailed(reason: str)[source]

Bases: object

Indicates evaluation was not able to complete successfully, with an error value (i.e. an exception).

class PARyOpt.evaluators.async.ValueNotReady[source]

Bases: object

Indicates a function value is not ready yet.

PARyOpt.evaluators.async_local module

class PARyOpt.evaluators.async_local.AsyncLocalEvaluator(job_generator: Callable[[str, <built-in function array>], NoneType], run_cmd_generator: Callable[[str, <built-in function array>], Union[str, List[Any]]], parse_result: Callable[[str, <built-in function array>], float], jobs_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/paryopt/checkouts/latest/docs/opt_jobs', required_fraction=1.0, max_pending=4)[source]

Bases: PARyOpt.evaluators.async.AsyncFunctionEvaluator

Class for cost functions that evaluated by launching a long-running process on the local machine.

Parameters:
  • job_generator – callable that sets up the run directory for a given x (by e.g. writing config files). It will be passed two arguments: the job directory and the point to evaluate at (x).
  • run_cmd_generator – callable that returns the command to run the job. It will be passed two arguments: the job directory and the point to evaluate at (x). If run_cmd_generator returns a string, the string will be run by the default shell (typically /bin/sh) via Popen with shell=True. If run_cmd_generator returns a list, it will be passed to Popen. In both cases, the CWD is set to the job directory.
  • parse_result – callable that returns the cost function evaluated at x. It will be passed two arguments: the job directory and the point to evaluate a t (x). This will be called after the command returned by run_cmd_generator has terminated (gracefully or otherwise). If the process did not terminate successfully or the result is otherwise unavailable, parse_result should raise any exception. This will signal the optimization routine to not try this point again.
  • jobs_dir – optional base directory to run jobs in - default is $PWD/opt_jobs.
  • required_fraction – fraction of points which must complete before continuing to the next iteration see AsyncEvaluator for more info and implementation
  • max_pending – maximum simultaneous processes, defaults to multiprocessing.cpu_count() see AsyncEvaluator for implementation
check_for_result(x: <built-in function array>, data: (<class 'str'>, <class 'int'>)) → Union[PARyOpt.evaluators.async.ValueNotReady, PARyOpt.evaluators.async.EvaluationFailed, PARyOpt.evaluators.async.EvaluateAgain, float][source]

Checks the status of pid, in data, and calls parse_result if the job is done.

Parameters:
  • x – location of function evaluation
  • data – list of directory and pid
Returns:

either ValueNotReady float or EvaluationFailed()

start(x: <built-in function array>) -> (<class 'str'>, <class 'int'>)[source]

Start a cost function evaluation at the given x location. This method may return anything - the data will be passed on to check_for_result(). The only restriction is that the return value should be pickle-able to enable restart support.

Parameters:x – point to begin evaluation at
Returns:user data that will be fed into check_for_result()

PARyOpt.evaluators.async_parse_result_local module

class PARyOpt.evaluators.async_parse_result_local.AsyncLocalParseResultEvaluator(parse_result: Callable[[str, <built-in function array>], float] = None, job_generator: Callable[[str, <built-in function array>], NoneType] = None, jobs_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/paryopt/checkouts/latest/docs/opt_jobs', wait_time: float = datetime.timedelta(0, 60), total_folders: int = 16, max_pending: int = 0, required_fraction: float = 1.0)[source]

Bases: PARyOpt.evaluators.async.AsyncFunctionEvaluator

Fills files in a set of folders and periodically checks if the external evaluator has finished evaluation. Supports asynchronous evaluations. Only on a local machine.

Variables:
  • folder_num – folder into which the location values are written into
  • job_generator – callable that sets up the run directory for a given x (by e.g. writing config files). It will be passed two arguments: the job directory and the point to evaluate at (x).
  • jobs_dir – base directory where the jobs are written into
  • parse_result – function to parse result from directory , if not specified, it will search in jobs_dir/folder_<folder_num>/if_parse.txt and y.txt
  • total_folders – total number of folders to write into
  • wait_time – min time to wait before parsing the results folder
check_for_result(x: <built-in function array>, data: (<class 'str'>, <class 'datetime.datetime'>)) → Union[PARyOpt.evaluators.async.ValueNotReady, PARyOpt.evaluators.async.EvaluationFailed, PARyOpt.evaluators.async.EvaluateAgain, float][source]

Function to check if a location has been evaluated or not (ValueNotReady). If it completes, categorize the result as one of a float , EvaluationFailed or EvaluateAgain

Parameters:
  • x – location to evaluate
  • data – directory
Returns:

Union[ValueNotReady, EvaluationFailed, EvaluateAgain, float]

start(x: <built-in function array>) -> (<class 'str'>, <class 'datetime.datetime'>)[source]

function to start a cost function evaluation (write to file in this case) given the location of evaluation

Parameters:x – location of evaluation
Returns:folder name in which it was submitted

PARyOpt.evaluators.async_sbatch module

class PARyOpt.evaluators.async_sbatch.AsyncSbatchEvaluator(host: PARyOpt.evaluators.connection.Host, job_generator: Callable[[str, <built-in function array>], NoneType], job_script: Union[str, Callable[[str, <built-in function array>], str]], lcl_parse_result: Callable[[str, str, PARyOpt.evaluators.connection.Connection, <built-in function array>], float] = None, remote_parse_result: Callable[[str, <built-in function array>], float] = None, lcl_jobs_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/paryopt/checkouts/latest/docs/opt_jobs', squeue_update_rate: datetime.timedelta = datetime.timedelta(0, 30), remote_jobs_dir: str = 'paryopt_jobs', required_fraction=1.0, max_pending=25)[source]

Bases: PARyOpt.evaluators.async.AsyncFunctionEvaluator

Class for cost functions that evaluated by launching a job on a remote machine running the SLURM job scheduler.

Parameters:
  • host – Host object containing the credentials for the server to connect to
  • job_generator – callable that sets up the run directory for a given x (by e.g. writing config files). It will be passed two arguments: the job directory and the point to evaluate at (x).
  • job_script – either a string (for a fixed job script), or a callable that returns the job script string. In the latter case, job_script will be passed two arguments: the job directory and the point to evaluate at (x).
  • remote_parse_result – callable that returns the cost function evaluated at x. It will be passed two arguments: the job directory and the point to evaluate at (x). This will be called after the command returned by run_cmd_generator has terminated (gracefully or otherwise). If the process did not terminate successfully or the result is otherwise unavailable, parse_result should raise any exception. This will signal the optimization routine to not try this point again. This function will be executed on the remote host. This requires the remote host to have a matching version of Python installed and the dill module.
  • lcl_parse_result – callable that returns the cost function evaluated at X. It is passed three arguments: the local job dir, remote job dir, the Connection object to the remote, and X. It is executed on the local machine. This does not require the remote to have Python installed.
  • lcl_jobs_dir – optional base directory to generate jobs in - default is $PWD/opt_jobs.
  • remote_jobs_dir – optional base directory to upload jobs to - default is $HOME/paryopt_jobs.
  • squeue_update_rate – minimum time between squeue calls. Lower for better job latency, higher to be more polite
  • required_fraction – fraction of points which must complete before continuing to the next iteration see AsyncEvaluator for more info and implementation
  • max_pending – maximum simultaneous queued jobs, defaults to 25, see AsyncEvaluator for implementation
check_for_result(x: <built-in function array>, data: (<class 'str'>, <class 'str'>, <class 'int'>, <class 'datetime.datetime'>)) → Union[PARyOpt.evaluators.async.ValueNotReady, PARyOpt.evaluators.async.EvaluateAgain, PARyOpt.evaluators.async.EvaluationFailed, float][source]

checks for result if the jobid is complete and ping time is after update rate

Parameters:
  • x – location of evaluation
  • data – data related to the location. Typically this is directory information, job id and submit time
Returns:

one of ValueNotReady, EvaluateAgain, EvaluationFailed or float

squeue()[source]
start(x: <built-in function array>) -> (<class 'str'>, <class 'str'>, <class 'int'>, <class 'datetime.datetime'>)[source]

Generate job directory on local machine, fill in data related to the job like directory, job id and submit time

PARyOpt.evaluators.async_sbatch.VALUE_FROM_FILE(filename)[source]

PARyOpt.evaluators.connection module

class PARyOpt.evaluators.connection.Connection[source]

Bases: object

call_on_remote(remote_func, *args, remote_cwd: Union[str, NoneType] = None)[source]

Call a function created on this system on a remote system with args. This is done by pickling it with dill, SFTPing it to a file on the remote, executing a Python script on the remote that un-dills the file, calls the function, dills the result and prints it to stdout. Finally, stdout is un-dilled on the local machine to give the return value. This requires the remote to have a matching Python version.

Parameters:
  • remote_func – function to call
  • args – any arguments to call the function with
  • remote_cwd – directory on the remote to call the script from (must have write access to this directory)
Returns:

value returned by f

connect(host: PARyOpt.evaluators.connection.Host)[source]
exec_command(cmd: str, cwd=None, check_exitcode=True, encoding='utf-8') -> (<class 'str'>, <class 'str'>, <class 'int'>)[source]

Executes cmd in a new shell session on the remote host.

Parameters:
  • cmd – command to execute
  • cwd – directory to execute the command in - performed by prepending ‘cd [cwd] && ‘ to cmd
  • check_exitcode – if true, instead of returning the exit code of cmd as part of the return tuple, verify that the return code is zero. If it is not, an exception is raised with the contents of stderr.
  • encoding – encoding to decode stdout/stderr with. Defaults to utf-8.
Returns:

if check_exitcode is True, (stdout: str, stderr: str). If it is False, (stdout, stderr, rc: int). stdout and stderr are decoded according to encoding.

get_dir(remote_dir: str, local_dir: str) → None[source]

Download directory from remote directory to local directory

get_file(remote_path: str, local_path: str) → None[source]

Downloads a file from the remote, same as paramiko.SFTPClient.get

mkdirs(remote_dir) → None[source]

Creates remote_dir recursively as a directory on the remote, creating any necessaries parent directories along the way. Similar to mkdir -p, except it doesn’t error if the directory already exists.

put_dir(local_path: str, remote_path: str) → None[source]

Compresses local_path into a .tar.gz archive, uploads it to the remote, extracts it into remote_path, and finally deletes the temporary tar archive. Assumes the remote has the ‘tar’ utility available.

put_file(local_path: str, remote_path: str) → None[source]

Uploads a local file to the remote host, same as paramiko.SFTPClient.put

remote_python() → str[source]

Returns a string that, when invoked as a command on the remote, will execute a Python that:

  • Matches the version that this script was invoked with (i.e. matching sys.version_info)
  • Has the ‘dill’ module installed

The remote Python is discovered by trial and error using common Python names. The search is performed once and then cached. If no such Python is available, this will return None.

sftp() → paramiko.sftp_client.SFTPClient[source]
class PARyOpt.evaluators.connection.Host(username, hostname, port=22)[source]

Bases: object

get_interactive(title: str, instructions: str, prompts: List[str]) → List[str][source]

Handles the ssh ‘interactive’ authentication mode (user answers a series of prompts).

Parameters:
  • title – title of the window
  • instructions – instructions, to be shown before any prompts
  • prompts – the list of prompts
Returns:

the list of responses (in the same order as the prompts)

get_keys()[source]
Returns:a list of public/private keys to try authenticating with
get_password()[source]
Returns:the password for the host

Module contents

class PARyOpt.evaluators.FunctionEvaluator(func: Callable[[<built-in function array>], float])[source]

Bases: object

The simplest function evaluator - evaluates a Python function for each point.

Parameters:func – cost function to evaluate at each x
evaluate_population(xs: List[<built-in function array>], old_xs: List[<built-in function array>] = []) → Tuple[List[Tuple[<built-in function array>, float]], List[<built-in function array>], List[<built-in function array>]][source]