From 7841fc40f02e54d83faa0646c8704c8d8e5a8714 Mon Sep 17 00:00:00 2001 From: Amanda Richardson Date: Thu, 31 Oct 2024 09:52:39 -0700 Subject: [PATCH 1/5] init push --- doc/application.rst | 199 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 doc/application.rst diff --git a/doc/application.rst b/doc/application.rst new file mode 100644 index 000000000..fa5b4e733 --- /dev/null +++ b/doc/application.rst @@ -0,0 +1,199 @@ +*********** +Application +*********** +======== +Overview +======== +The ``Application`` class facilitates the execution of computational tasks within an ``Experiment`` workflow. +These tasks can include launching compiled applications, running scripts, or performing general +computational operations. ``Application(s)`` integrate into ``Job(s)``, where ``LaunchSettings`` provide +launcher-specific behavior for the ``Job``. + +========== +Initialize +========== +This section details the steps to set up the parameters that control your application's initialization. + +**Step 1: Import Application** + +After installing Smartsim, ``Application`` may be imported in Python code like: + +.. code-block:: python + + from smartsim import Application + +**Step 2: Set the Application Name and Executable** + +Set the application name and executable. The `name` is a string that identifies the application, and +`exe` is the string path to the executable. Optionally, you can provide `exe_args` as a string or sequence of +of strings to specify arguments for the executable. + +* `name`: A string that identifies the application. Example: + + .. code-block:: python + + name="my_app" + +* `exe`: A string that specifies the path to the executable. If only the executable name is provided, SmartSim + will attempt to locate the path on the system. Examples: + + .. code-block:: python + + exe = "/path/to/new_executable" + + .. code-block:: python + + exe = "new_executable" + +* `exe_args`: An optional argument that can be a string or a sequence of strings, representing the arguments + for the executable. Examples: + + .. code-block:: python + + exe_args="--arg1 value1 --arg2 value2" + + .. code-block:: python + + exe_args=["--arg1", "value1", "--arg2", "value2"] + +**Example initializing an Application:** Once you have imported ``Application`` using ``from smartsim +import Application``, initialize an ``Application``. For example: + +.. code-block:: python + + app = Application( + name="my_app", + exe="/path/to/executable", + exe_args="--arg1 value1 --arg2 value2" + ) + +========= +Configure +========= +After initializing an ``Application`` object, configure the ``exe``, ``exe_args``, or ``files`` attribute. If the simulation +requires specific parameters, attach configuration files via the ``Application.files`` attribute. This attribute also +supports copying or symlinking files into the job's run directory to ensure accessibility during the simulation. +To reuse an application but alter the system state, update the ``exe_args`` attribute. To change the executable while keeping +the same arguments, modify the ``exe`` attribute. + +Executable +========== +To reset the executable after initializing the ``Application`` object, assign the desired executable path to the ``exe`` +attribute. If only the executable name is specified, SmartSim will attempt to locate the executable path on the +machine. For example: + +.. code-block:: python + + # Set the executable path + my_app.exe = "/path/to/new_executable" + + # or just the executable name + my_app.exe = "new_executable" + +Executable Arguments +==================== +There are two methods to configure ``exe_args``: + +1. Use ``Application.exe_args`` to overwrite the existing executable arguments. +2. Use ``Application.add_exe_args`` to add to the existing executable arguments. + +**Option 1: Use Application.exe_args** + +Set the executable arguments directly by assigning a list of arguments or a string argument +to the ``exe_args`` attribute. This will overwrite any previously set executable arguments. +For example: + + .. code-block:: python + + my_app.exe_args = ["arg1", "arg2"] + + my_app.exe_args = "arg1" + +**Option 2: Use Application.add_exe_args** + +To add additional executable arguments after initializing the ``Application`` object, use the +``add_exe_args`` method. This method appends the new arguments to the existing ``exe_args`` without +overwriting them. For example: + + .. code-block:: python + + my_app.add_exe_args(["new_arg1", "new_arg2"]) + + my_app.add_exe_args("new_arg1") + +Input Files +=========== +In this section, we will explore how to attach files to an application using the ``Application.files`` +attribute. This attribute allows users to add files through three different operations: + +1. Copying +2. Creating symlinks +3. Configuring files + +Each file operation can be added to the `files` attribute of the ``Application`` instance. + +---- +Copy +---- +Copying files involves creating a duplicate of the source file at the destination path. This is useful +when you need to ensure that the original file remains unchanged while providing a copy for the application +to use. + +**Adding a Copy Operation:** +To add a copy operation, use the `add_copy` method on the `files` attribute of the ``Application`` instance. +This method requires the absolute source path (`src`) and the relative destination path (`dest`) to be of +type ``pathlib.Path``. For example: + +.. code-block:: python + + my_app.files.add_copy( + src=pathlib.Path("/path/to/source"), + dest=pathlib.Path("destination") + ) + +This will create a copy of the file located at `"/path/to/source"` and place it at `"/path/to/destination"`. + +------- +Symlink +------- +Creating symlinks involves creating a symbolic link from the source file to the destination path. This +is useful when you want to reference the original file without duplicating it. + +**Adding a Symlink Operation:** +To add a symlink operation, use the `add_symlink` method on the `files` attribute of the ``Application`` instance. +This method requires the absolute source path (`src`) and the relative destination path (`dest`) to be of type +pathlib.Path. For example: + +.. code-block:: python + + my_app.files.add_symlink( + src=pathlib.Path("/path/to/source"), + dest=pathlib.Path("destination") + ) + +This will create a symbolic link from the file located at `"/path/to/source"` to `"/path/to/destination"`. + +--------- +Configure +--------- +Configuring files involves modifying the content of the source file based on specified parameters and +then placing the modified file at the destination path. This is useful for setting up configuration +files with dynamic content. + +**Adding a Configure Operation:** +To add a configure operation, use the ``add_configuration`` method on the ``files`` attribute of the ``Application`` +instance. This method requires the absolute source path (``src``), the relative destination path (``dest``), and the file parameters +(``file_parameters``) to be of type mapping of string to strings. Additionally, you can specify a tag +(``tag``) to identify the configuration. For example: + +.. code-block:: python + + my_app.files.add_configuration( + src=pathlib.Path("/path/to/source"), + file_parameters={"key": "value"}, + dest=pathlib.Path("destination"), + tag=";" + ) + +This will modify the content of the file located at `"/path/to/source"` based on the specified parameters and +place the modified file at `"/path/to/destination"`. \ No newline at end of file From 20f6f1147f15ff8b21d44278bf4685d995bebd6a Mon Sep 17 00:00:00 2001 From: Amanda Richardson Date: Thu, 31 Oct 2024 16:19:48 -0700 Subject: [PATCH 2/5] update application --- doc/application.rst | 52 ++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/doc/application.rst b/doc/application.rst index fa5b4e733..39bf688f1 100644 --- a/doc/application.rst +++ b/doc/application.rst @@ -12,7 +12,8 @@ launcher-specific behavior for the ``Job``. ========== Initialize ========== -This section details the steps to set up the parameters that control your application's initialization. +The ``Application`` class allows you to set your jobs program. +This section details the steps to set up the input parameters for your application. **Step 1: Import Application** @@ -24,9 +25,8 @@ After installing Smartsim, ``Application`` may be imported in Python code like: **Step 2: Set the Application Name and Executable** -Set the application name and executable. The `name` is a string that identifies the application, and -`exe` is the string path to the executable. Optionally, you can provide `exe_args` as a string or sequence of -of strings to specify arguments for the executable. +The `name` is a string that identifies the application, and `exe` is the string path to the executable. +Optionally, you can provide `exe_args` as a string or sequence of strings to specify arguments for the executable. * `name`: A string that identifies the application. Example: @@ -41,8 +41,6 @@ of strings to specify arguments for the executable. exe = "/path/to/new_executable" - .. code-block:: python - exe = "new_executable" * `exe_args`: An optional argument that can be a string or a sequence of strings, representing the arguments @@ -52,8 +50,6 @@ of strings to specify arguments for the executable. exe_args="--arg1 value1 --arg2 value2" - .. code-block:: python - exe_args=["--arg1", "value1", "--arg2", "value2"] **Example initializing an Application:** Once you have imported ``Application`` using ``from smartsim @@ -70,15 +66,15 @@ import Application``, initialize an ``Application``. For example: ========= Configure ========= -After initializing an ``Application`` object, configure the ``exe``, ``exe_args``, or ``files`` attribute. If the simulation -requires specific parameters, attach configuration files via the ``Application.files`` attribute. This attribute also -supports copying or symlinking files into the job's run directory to ensure accessibility during the simulation. -To reuse an application but alter the system state, update the ``exe_args`` attribute. To change the executable while keeping -the same arguments, modify the ``exe`` attribute. +After initializing an ``Application`` object, you might want to configure the ``exe``, ``exe_args``, or ``files`` attributes. +If an executable requires specific parameters, attach configuration files using the ``Application.files`` attribute. This attribute also +supports copying or symlinking files into the job's run directory to ensure access at simulation runtime. To reuse an application but +alter the system state, update or overwrite the ``exe_args`` attribute. To change the executable while keeping the same arguments, +overwrite the ``exe`` attribute. Executable ========== -To reset the executable after initializing the ``Application`` object, assign the desired executable path to the ``exe`` +To overwrite the executable after initializing the ``Application`` object, assign the desired executable path to the ``exe`` attribute. If only the executable name is specified, SmartSim will attempt to locate the executable path on the machine. For example: @@ -123,25 +119,25 @@ overwriting them. For example: Input Files =========== -In this section, we will explore how to attach files to an application using the ``Application.files`` +In this section, we explore how to attach files to an application using the ``Application.files`` attribute. This attribute allows users to add files through three different operations: 1. Copying 2. Creating symlinks 3. Configuring files -Each file operation can be added to the `files` attribute of the ``Application`` instance. +Each file operation can be added to the ``files`` attribute of the ``Application`` instance. ---- Copy ---- -Copying files involves creating a duplicate of the source file at the destination path. This is useful -when you need to ensure that the original file remains unchanged while providing a copy for the application +Copying files involves creating a duplicate of the source file or folder at the destination path. This is useful +when you need to ensure that the original file remains unchanged while providing a copy for the executable to use. **Adding a Copy Operation:** -To add a copy operation, use the `add_copy` method on the `files` attribute of the ``Application`` instance. -This method requires the absolute source path (`src`) and the relative destination path (`dest`) to be of +To add a copy operation, use the ``add_copy`` method on the ``files`` attribute of the ``Application`` instance. +This method requires the absolute source path (``src``) and an optional relative destination path (``dest``) to be of type ``pathlib.Path``. For example: .. code-block:: python @@ -151,7 +147,8 @@ type ``pathlib.Path``. For example: dest=pathlib.Path("destination") ) -This will create a copy of the file located at `"/path/to/source"` and place it at `"/path/to/destination"`. +This will create a copy of the file located at `"/path/to/source"` and place it within the job's +run directory at `"/job/run/destination"`. ------- Symlink @@ -160,8 +157,8 @@ Creating symlinks involves creating a symbolic link from the source file to the is useful when you want to reference the original file without duplicating it. **Adding a Symlink Operation:** -To add a symlink operation, use the `add_symlink` method on the `files` attribute of the ``Application`` instance. -This method requires the absolute source path (`src`) and the relative destination path (`dest`) to be of type +To add a symlink operation, use the ``add_symlink`` method on the ``files`` attribute of the ``Application`` instance. +This method requires the absolute source path (``src``) and an optional relative destination path (``dest``) to be of type pathlib.Path. For example: .. code-block:: python @@ -171,7 +168,8 @@ pathlib.Path. For example: dest=pathlib.Path("destination") ) -This will create a symbolic link from the file located at `"/path/to/source"` to `"/path/to/destination"`. +This will create a symbolic link from the file located at `"/path/to/source"` to the job's +run directory at `"/job/run/destination"`. --------- Configure @@ -182,8 +180,8 @@ files with dynamic content. **Adding a Configure Operation:** To add a configure operation, use the ``add_configuration`` method on the ``files`` attribute of the ``Application`` -instance. This method requires the absolute source path (``src``), the relative destination path (``dest``), and the file parameters -(``file_parameters``) to be of type mapping of string to strings. Additionally, you can specify a tag +instance. This method requires the absolute source path (``src``), an optional relative destination path (``dest``), and the file parameters +(``file_parameters``) to be of type mapping of string to strings. Additionally, you can specify an optional tag (``tag``) to identify the configuration. For example: .. code-block:: python @@ -196,4 +194,4 @@ instance. This method requires the absolute source path (``src``), the relative ) This will modify the content of the file located at `"/path/to/source"` based on the specified parameters and -place the modified file at `"/path/to/destination"`. \ No newline at end of file +place the modified file at `"/job/run/destination"`. \ No newline at end of file From f08cda5a2bb1e4a9bac493a112defd264bfa38df Mon Sep 17 00:00:00 2001 From: Amanda Richardson Date: Fri, 1 Nov 2024 14:15:52 -0700 Subject: [PATCH 3/5] update configure to modify --- doc/application.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/application.rst b/doc/application.rst index 39bf688f1..9107d0436 100644 --- a/doc/application.rst +++ b/doc/application.rst @@ -63,9 +63,9 @@ import Application``, initialize an ``Application``. For example: exe_args="--arg1 value1 --arg2 value2" ) -========= -Configure -========= +====== +Modify +====== After initializing an ``Application`` object, you might want to configure the ``exe``, ``exe_args``, or ``files`` attributes. If an executable requires specific parameters, attach configuration files using the ``Application.files`` attribute. This attribute also supports copying or symlinking files into the job's run directory to ensure access at simulation runtime. To reuse an application but From e601a9818e46df2988d86d271a54adade0d3262d Mon Sep 17 00:00:00 2001 From: Amanda Richardson Date: Sun, 3 Nov 2024 23:10:01 -0800 Subject: [PATCH 4/5] pushing to test ls --- doc/application.rst | 56 +++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/doc/application.rst b/doc/application.rst index 9107d0436..24cdab87c 100644 --- a/doc/application.rst +++ b/doc/application.rst @@ -5,15 +5,16 @@ Application Overview ======== The ``Application`` class facilitates the execution of computational tasks within an ``Experiment`` workflow. -These tasks can include launching compiled applications, running scripts, or performing general +These tasks include launching compiled applications, running scripts, or performing general computational operations. ``Application(s)`` integrate into ``Job(s)``, where ``LaunchSettings`` provide launcher-specific behavior for the ``Job``. ========== Initialize ========== -The ``Application`` class allows you to set your jobs program. -This section details the steps to set up the input parameters for your application. +A ``Application`` requires two input arguments: name and executable. Optionally, users may +provide executable arguments. This section details argument names, argument types +and how to use the arguments to initialize an ``Application``. **Step 1: Import Application** @@ -23,10 +24,10 @@ After installing Smartsim, ``Application`` may be imported in Python code like: from smartsim import Application -**Step 2: Set the Application Name and Executable** +**Step 2: Set the Application Name, Executable and Executable Arguments** The `name` is a string that identifies the application, and `exe` is the string path to the executable. -Optionally, you can provide `exe_args` as a string or sequence of strings to specify arguments for the executable. +Optionally, you can provide `exe_args` as a string or sequence of strings. * `name`: A string that identifies the application. Example: @@ -43,7 +44,7 @@ Optionally, you can provide `exe_args` as a string or sequence of strings to spe exe = "new_executable" -* `exe_args`: An optional argument that can be a string or a sequence of strings, representing the arguments +* `exe_args`: An optional argument of type string or sequence of strings, representing the arguments for the executable. Examples: .. code-block:: python @@ -52,11 +53,12 @@ Optionally, you can provide `exe_args` as a string or sequence of strings to spe exe_args=["--arg1", "value1", "--arg2", "value2"] -**Example initializing an Application:** Once you have imported ``Application`` using ``from smartsim -import Application``, initialize an ``Application``. For example: +**Example initialize an Application:** .. code-block:: python + from smartsim import Application + app = Application( name="my_app", exe="/path/to/executable", @@ -66,24 +68,19 @@ import Application``, initialize an ``Application``. For example: ====== Modify ====== -After initializing an ``Application`` object, you might want to configure the ``exe``, ``exe_args``, or ``files`` attributes. -If an executable requires specific parameters, attach configuration files using the ``Application.files`` attribute. This attribute also -supports copying or symlinking files into the job's run directory to ensure access at simulation runtime. To reuse an application but -alter the system state, update or overwrite the ``exe_args`` attribute. To change the executable while keeping the same arguments, -overwrite the ``exe`` attribute. +This section explains how to modify the attached executable and executable arguments. Additionally, +learn how to attach copy, symlink and configuration files to an initialized ``Application``. Executable ========== -To overwrite the executable after initializing the ``Application`` object, assign the desired executable path to the ``exe`` -attribute. If only the executable name is specified, SmartSim will attempt to locate the executable path on the +To overwrite the executable, assign the desired executable path to the ``exe`` attribute. +If only the executable name is specified, SmartSim will attempt to locate the executable path on the machine. For example: .. code-block:: python - # Set the executable path my_app.exe = "/path/to/new_executable" - # or just the executable name my_app.exe = "new_executable" Executable Arguments @@ -119,23 +116,24 @@ overwriting them. For example: Input Files =========== -In this section, we explore how to attach files to an application using the ``Application.files`` -attribute. This attribute allows users to add files through three different operations: +This section details how to attach files to an ``Application``. SmartSim supports three file operations: + +1. :ref:`Copy` +2. :ref:`Symlink` +3. :ref:`Configure` -1. Copying -2. Creating symlinks -3. Configuring files +The ``Application.files`` attribute enables adding file operations. Continue to the operation +sections for further details. -Each file operation can be added to the ``files`` attribute of the ``Application`` instance. +.. _app_file_copy: ---- Copy ---- -Copying files involves creating a duplicate of the source file or folder at the destination path. This is useful -when you need to ensure that the original file remains unchanged while providing a copy for the executable -to use. +The copy operation involves creating a duplicate of the source file or folder at the destination +path within the job's run directory. -**Adding a Copy Operation:** +**Add a Copy Operation:** To add a copy operation, use the ``add_copy`` method on the ``files`` attribute of the ``Application`` instance. This method requires the absolute source path (``src``) and an optional relative destination path (``dest``) to be of type ``pathlib.Path``. For example: @@ -150,6 +148,8 @@ type ``pathlib.Path``. For example: This will create a copy of the file located at `"/path/to/source"` and place it within the job's run directory at `"/job/run/destination"`. +.. _app_file_symlink: + ------- Symlink ------- @@ -171,6 +171,8 @@ pathlib.Path. For example: This will create a symbolic link from the file located at `"/path/to/source"` to the job's run directory at `"/job/run/destination"`. +.. _app_file_configure: + --------- Configure --------- From 7501fe18c7895a2414616149a2178e12e467c977 Mon Sep 17 00:00:00 2001 From: Amanda Richardson Date: Mon, 4 Nov 2024 09:19:26 -0800 Subject: [PATCH 5/5] updates --- doc/application.rst | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/doc/application.rst b/doc/application.rst index 24cdab87c..dc1c74bc3 100644 --- a/doc/application.rst +++ b/doc/application.rst @@ -122,8 +122,8 @@ This section details how to attach files to an ``Application``. SmartSim support 2. :ref:`Symlink` 3. :ref:`Configure` -The ``Application.files`` attribute enables adding file operations. Continue to the operation -sections for further details. +The ``Application.files`` attribute enables adding the file operations. Continue to the operation +sections for further explanation. .. _app_file_copy: @@ -134,8 +134,8 @@ The copy operation involves creating a duplicate of the source file or folder at path within the job's run directory. **Add a Copy Operation:** -To add a copy operation, use the ``add_copy`` method on the ``files`` attribute of the ``Application`` instance. -This method requires the absolute source path (``src``) and an optional relative destination path (``dest``) to be of +To add a copy operation, use the ``add_copy`` method on ``Application.files``. This method requires +an absolute source path (``src``) and an optional relative destination path (``dest``) of type ``pathlib.Path``. For example: .. code-block:: python @@ -153,13 +153,13 @@ run directory at `"/job/run/destination"`. ------- Symlink ------- -Creating symlinks involves creating a symbolic link from the source file to the destination path. This -is useful when you want to reference the original file without duplicating it. +The symlink operation involves creating a symbolic link from the source file to the destination path +within the job's run directory. -**Adding a Symlink Operation:** -To add a symlink operation, use the ``add_symlink`` method on the ``files`` attribute of the ``Application`` instance. -This method requires the absolute source path (``src``) and an optional relative destination path (``dest``) to be of type -pathlib.Path. For example: +**Add a Symlink Operation:** +To add a symlink operation, use the ``add_symlink`` method on ``Application.files``. This method requires +the absolute source path (``src``) and an optional relative destination path (``dest``) of type +``pathlib.Path``. For example: .. code-block:: python @@ -176,14 +176,13 @@ run directory at `"/job/run/destination"`. --------- Configure --------- -Configuring files involves modifying the content of the source file based on specified parameters and -then placing the modified file at the destination path. This is useful for setting up configuration -files with dynamic content. - -**Adding a Configure Operation:** -To add a configure operation, use the ``add_configuration`` method on the ``files`` attribute of the ``Application`` -instance. This method requires the absolute source path (``src``), an optional relative destination path (``dest``), and the file parameters -(``file_parameters``) to be of type mapping of string to strings. Additionally, you can specify an optional tag +The configure operation involves modifying the content of the source file based on specified parameters and +then placing the modified file at the destination path. + +**Add a Configure Operation:** +To add a configure operation, use the ``add_configuration`` method on ``Application.files``. +This method requires the absolute source path (``src``), an optional relative destination path (``dest``), and file parameters +(``file_parameters``) of type mapping of string to strings. Additionally, specify an optional tag (``tag``) to identify the configuration. For example: .. code-block:: python