schrodinger.job.app module

Deprecated for schrodinger.job.launchapi.

A base class for applications that can be run under job control.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.job.app.App(script, args=[])

Bases: object

__init__(script, args=[])

run()

If ‘-gui’ passed to the constructor, runs the GUI OR…

Reads the restart file (-RESTART, existing job) or command-line arguments (default, new job) and then runs in startup mode (default) or backend mode (-NOJOBID).

Raises a SyntaxError if the commandLine() method returns no arguments.

commandLine(args)

Overwrite this method with code that parses the arguments and initializes the instance variables to appropriate values. This method should also set the job name and input/output files for the scriptlauncher via dedicated App methods. The method should return a revised list of arguments (e.g., removing arguments that won’t be needed when running the backend on the restart file). Output files also can be registered in the backend() method.

gui()

Overwrite this method with your GUI code. When a job is ready to be submited, call ‘self.launchBackend()’ with appropriate arguments. ‘launchBackend’ then will run the rerun the script in non-GUI mode, so the argument list should be like a command-line invocation.

Ex: self.launchBackend([‘-i’, input_file, ‘-j’, ‘testjob’,

‘-HOST’, hostname, ‘-USER’, myname])

backend()

Overwrite this function with your backend (main) code. This method also may set output files via dedicated App methods for jobs that are running under Job Control. To enable restartability at intermediate stages of the job, record the state of the job in an instance variable, have the method base its actions on the current state, and periodically save the instance via the dumpBE() method.

dumpFE(relpath='.')

Dumps the App instance to file named ‘<jobname>.restart’. This version is called on the front end to create the initial restart file during job submission. This is the file from which a user would resume an interrupted job via a command like…

<myapp>.py -RESTART

When the user runs the application with ‘-RESTART’ option, the App instance is recovered from the dump file instead of initializing the instance via the commandLine() method.

If the job was submitted with -LOCAL, then the restart file will be in the launch directory, otherwise restart file will be in the <jobname>.zip archive that is created by jobcontrol.

A ‘relpath’ optional argument is available, in case the restart file needs to be written somewhere other than the CWD (e.g., in case the backend is running in a workdir).

dumpBE(relpath='.')

Dumps the App instance to file named ‘<jobname>.restart’. This function is to be called by backend() at restartable places in the code. This is the file from which a user would resume an interrupted job via a command like…

<myapp>.py -RESTART

When the user runs the application with ‘-RESTART’ option, the App instance is recovered from the dump file instead of initializing the instance via the commandLine() method.

If the job was submitted with -LOCAL, then the restart file will be in the launch directory, otherwise restart file will be in the <jobname>.zip archive that is created by jobcontrol.

A ‘relpath’ optional argument is available, in case the restart file needs to be written somewhere other than the CWD (e.g., in case the backend is running in a workdir).

setJobName(jobname)

Call this method from commandLine() to set the jobname.

getJobName()

Returns the jobname of the App.

setProgramName(progname)

Call this method from commandLine() to set the program name.

getProgramName()

Returns the program name of the App.

getHostStr()

What user specified as -HOST when running the script. Use in backend() when running jobs with JobDJ. Should be in format…

“host1:ncpu1 host2:ncpu2”

NOTE: NOT COMPLETE YET. ALSO, THIS INFORMATION IS AVAILABLE TO JOBDJ

VIA THE SCHRODINGER_NODEFILE.

alwaysLocal()

Call this method from the commandLine() method to make the backend always run in the local (i.e., launch) directory instead of in a scratch directory. This enforces -LOCAL without the user having to use that command-line option. Running in the local directory removes the need to use addInputFile(), addOutputFile*(), etc., but it imposes a requirement that the local directory be directly accessible to any machine where the backend will run, which may or may not be true for remote jobs. Running locally also can facilitate restarting if the backend is a driver for other subjobs.

useLocalDriver()

The backend will be run on the local host, regardless of the -HOST setting. This is so the -HOST option can be used to set the subjob host info, while letting the driver/backend run locally.

addInputFile(file)

Call from commandLine() to specify job input files.

addOutputFileFE(file)

Call from commandLine() to specify output files.

addOutputFileBE(file)

Call from backend() to specify output files.

setStructureOutputFileFE(file)

Call from commandLine() to specify the structure output file (i.e., the file that gets incorporated into Maestro upon job completion).

setStructureOutputFileBE(file)

Call from backend() to specify the structure output file (i.e., the file that gets incorporated into Maestro upon job completion).

addLogFile(file)

Call from commandLine() to specify additional log files. The main log file (i.e., the stdout/stderr of the backend() is registered automatically.

log(*args)

Use this method to print from within backend().

lognotret(*args)

Use this method to print from within backend(). Unlike log(), it does not print a carriage return at end of logged text.

launchBackend(args=[])

Call this method from the gui() method to run the job. Returns the Job object of the launched job. In order to set up the appropriate environment variables, a top-level script must be called. Therefore, launchBackend() will invoke the script in command-line mode, with all arguments passed to it. The ‘args’ should be a list of command-line arguments (e.g., [‘-i’, input_file, ‘-HOST’, hostname]).

Return type

jobcontrol.Job object

Returns

The job object for the launched backend job.

Raises

RuntimeError – If there is a problem launching the job (e.g., no JobId gets printed). If running within Maestro, an error dialog will first be shown to the user.

addCommandLineOptions(parser, distributed=False, use_group=False)

Add top-level and App options to the OptionParser ‘parser’. With this method, the application-specific parser can include top-level and App options in its usage/help statement, though the actual parsing of those arguments is handled elsewhere. The ‘distributed’ boolean option (default is False) alters the option descriptions slightly, making references to the job as the “driver job”. If ‘use_group’ is True (default is False), the options will be added as an OptionGroup.