Skip to contents

Run pyDarwin Model Search

run_pyDarwin.Rd

This function executes a pyDarwin model search by calling the specified Python interpreter and the darwin.run_search module.

Usage

run_pyDarwin(
  InterpreterPath,
  Flags = c("-u", "-m"),
  DirectoryPath = ".",
  TemplatePath = "template.txt",
  TokensPath = "tokens.json",
  OptionsPath = "options.json",
  Wait = TRUE
)

Arguments

InterpreterPath

Character string. The full path to the Python interpreter executable (e.g., python.exe or python).

Flags

Character vector. Optional flags passed directly to the Python interpreter. Defaults to c("-u", "-m"). -u forces unbuffered binary stdout and stderr streams. -m runs a library module as a script and is essential for calling darwin.run_search.

DirectoryPath

Character string. Optional path to the directory containing the template.txt, tokens.json, and options.json files. If provided, this path is used to locate these files, overriding any directory information in the TemplatePath, TokensPath, and OptionsPath arguments (a warning will be issued). Defaults to the current R working directory.

TemplatePath

Character string. Path to the pyDarwin template file (typically template.txt). If DirectoryPath is specified, only the basename of TemplatePath is used, combined with DirectoryPath.

TokensPath

Character string. Path to the pyDarwin tokens JSON file (typically tokens.json). If DirectoryPath is specified, only the basename of TokensPath is used, combined with DirectoryPath.

OptionsPath

Character string. Path to the pyDarwin options JSON file (typically options.json). This file defines run settings like working_dir, output_dir, etc. If DirectoryPath is specified, only the basename of OptionsPath is used, combined with DirectoryPath.

Wait

Logical. If TRUE (default), R waits for the pyDarwin process to complete before proceeding. If FALSE, R launches the pyDarwin process in the background and returns immediately. See the 'Background Execution' section for important details when using Wait = FALSE.

Value

  • If Wait = TRUE: A list containing the search results read from the output_dir (specified in options.json). This typically includes:

    • results: A data frame (results.csv).

    • FinalResultFile: Character vector containing lines from the final model's result file (e.g., .lst, .txt).

    • FinalControlFile: Character vector containing lines from the final model's control file (e.g., .mod, .mmdl).

    If result files are not found, warnings are issued. If no results are found but messages.txt exists, its content might be returned with a warning. If the Python call fails (non-zero exit code), the function stops with an error.

  • If Wait = FALSE: A character string giving the full path to the main pyDarwin log file (messages.txt) within the working_dir.

Background Execution (Wait = FALSE)

When Wait is set to FALSE, the pyDarwin process is launched in the background, and the R function returns immediately. This allows R to continue processing while pyDarwin runs.

  • Output Redirection: Standard output (stdout) and standard error (stderr) from the Python process are redirected to files named stdout.log and stderr.log respectively, within the working_dir. These files are crucial for diagnosing issues if the background process fails or behaves unexpectedly.

  • Primary Log: The main pyDarwin log file (messages.txt, located in the working_dir) remains the primary source for detailed run information, but the stdout.log and stderr.log capture console output and errors directly.

See also

run_pyDarwinRemote(), reconnect_pyDarwinJob()

Examples

if (FALSE) { # \dontrun{
# Example: Running pyDarwin and waiting for results
# Assuming python is in the PATH and input files are in 'my_project'

results <- run_pyDarwin(
  InterpreterPath = "python",
  DirectoryPath = "my_project",
  Wait = TRUE
)
print(results$results)

# Example: Launching pyDarwin in the background

log_file_path <- run_pyDarwin(
  InterpreterPath = "python",
  DirectoryPath = "my_project",
  Wait = FALSE
)
} # }