Merge pull request #303 from xylar/reorg-tasks

Reorganize tasks in `polaris.tasks.{component}`

Author: xylar

docs/developers_guide/api.md

@@ -190,7 +190,7 @@ seaice/api
 ### components
 
 ```{eval-rst}
-.. currentmodule:: polaris.components
+.. currentmodule:: polaris.tasks
 
 .. autosummary::
    :toctree: generated/

docs/developers_guide/docs.md

@@ -21,7 +21,7 @@ For examples, see:
 - {ref}`dev-ocean` in the Developer's Guide
 - {ref}`dev-ocean-baroclinic-channel` tasks in the Developer's Guide
 
-Documentation for each component in the User's guide should include a label 
+Documentation for each component in the User's guide should include a label
 with the name of the component:
 
 ```markdown
@@ -42,8 +42,8 @@ In the Developer's Guide, labels have `dev-` prepended to them:
 
 Each category of tasks (e.g. baroclinic channel) should have its own page in
 the `tasks` subdirectory of the component. The label for the page should have
-have the component name prepended (to make sure it's unique), and each task 
-(if explicitly labeled) should have the component and category of tasks 
+have the component name prepended (to make sure it's unique), and each task
+(if explicitly labeled) should have the component and category of tasks
 prepended to it. Thus, in the User's guide, we have:
 
 ```markdown
@@ -84,7 +84,7 @@ case, including:
 
 - A page for each category of tasks with a section for each task:
 
-  - A citation or link where the test case that is the basis for the tasks is 
+  - A citation or link where the test case that is the basis for the tasks is
     defined (if any)
   - A brief overview of the common characteristics of the tasks
   - An image showing typical output from one of the tasks
@@ -93,14 +93,14 @@ case, including:
   - The following sections as described in the template: description, mesh,
     vertical grid, initial conditions, forcing, time step, config, and cores
 
-- A description of any common framework within the component that the test 
+- A description of any common framework within the component that the test
   group or task pages may need to refer to.  This should only include
-  framework that users may need to be aware of, e.g. because of 
+  framework that users may need to be aware of, e.g. because of
   {ref}`config-files` or namelist options they may wish to edit.
 
 - A description of each suite, including which tasks are included
 
-A template is available for documenting groups of related tasks in the User's 
+A template is available for documenting groups of related tasks in the User's
 Guide: {ref}`ocean-category-of-task`
 
 The Developer's guide for each component should contain:
@@ -113,22 +113,22 @@ The Developer's guide for each component should contain:
     this category
   - A description of shared config, namelist and streams files
   - A description of shared steps
-  - A description of any other shared framework code shared between the tasks 
+  - A description of any other shared framework code shared between the tasks
     in that category
   - A description of each task and its steps
 
 - Technical details on the shared framework for the component
 
 Finally, all functions in the tasks and their shared framework that are part of
-the public API (i.e. all functions that don't start with an underscore) should 
+the public API (i.e. all functions that don't start with an underscore) should
 be added to `docs/<component>/api.md`:
 
 ````markdown
 
 ### baroclinic_channel
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.baroclinic_channel
+.. currentmodule:: polaris.tasks.ocean.baroclinic_channel
 
 .. autosummary::
    :toctree: generated/

docs/developers_guide/framework/config.md

@@ -22,7 +22,7 @@ The {py:meth}`mpas_tools.config.MpasConfigParser.add_from_package()` method can
 be used to add the contents of a config file within a package to the config
 options. Examples of this can be found in many tasks as well as in the
 `polaris.setup` module. Here is a typical example from
-{py:class}`polaris.ocean.tasks.inertial_gravity_wave.InertialGravityWave`:
+{py:class}`polaris.tasks.ocean.inertial_gravity_wave.InertialGravityWave`:
 
 ```python
 from polaris import Task
@@ -33,11 +33,11 @@ class InertialGravityWave(Task):
         name = 'inertial_gravity_wave'
         subdir = f'planar/{name}'
         super().__init__(component=component, name=name, subdir=subdir)
-        
+
         ...
 
         self.config.add_from_package(
-            'polaris.ocean.tasks.inertial_gravity_wave',
+            'polaris.tasks.ocean.inertial_gravity_wave',
             'inertial_gravity_wave.cfg')
 ```
 
@@ -48,8 +48,8 @@ the file is in the path `polaris/ocean/tasks/baroclinic_channel`
 that the config file should always exist, so we would like the code to raise
 an exception (`exception=True`) if the file is not found.  This is the
 default behavior.  In some cases, you would like the code to add the config
-options if the config file exists and do nothing if it does not.  In this 
-example from {py:func}`polaris.setup.setup_task()`, there may not be a config 
+options if the config file exists and do nothing if it does not.  In this
+example from {py:func}`polaris.setup.setup_task()`, there may not be a config
 file for the particular machine we're on, and that's fine:
 
 ```python
@@ -81,30 +81,30 @@ of functions (`range()`, {py:meth}`numpy.linspace()`,
 
 ## Shared config files
 
-Often, it makes sense for many tasks and steps to share the same config 
+Often, it makes sense for many tasks and steps to share the same config
 options.  The default behavior is for a task and its "owned" steps to share
-a config file in the task's work directory called `{task.name}.cfg` and 
+a config file in the task's work directory called `{task.name}.cfg` and
 symlinks with that same name in each step's work directory.  The default for
 a shared step is to have its own `{step.name}.cfg` in its work directory.
 
 Developers can create shared config parsers that define the location of the
 shared config file and add them to tasks and steps using
-{py:meth}`polaris.Task.set_shared_config()` and 
+{py:meth}`polaris.Task.set_shared_config()` and
 {py:meth}`polaris.Step.set_shared_config()`.  The location of the shared
 config file should be intuitive to users but local symlinks will also make
 it easy to modify the shared config options from within any of the tasks and
 steps that use them.
 
-As an example, the baroclinic channel tasks share a single 
+As an example, the baroclinic channel tasks share a single
 `baroclinic_channel.cfg` config file for each resolution that resides in the
 resolution's work directory:
 
 ```python
 from polaris.config import PolarisConfigParser
 from polaris.ocean.resolution import resolution_to_subdir
-from polaris.ocean.tasks.baroclinic_channel.default import Default
-from polaris.ocean.tasks.baroclinic_channel.init import Init
-from polaris.ocean.tasks.baroclinic_channel.rpe import Rpe
+from polaris.tasks.ocean.baroclinic_channel.default import Default
+from polaris.tasks.ocean.baroclinic_channel.init import Init
+from polaris.tasks.ocean.baroclinic_channel.rpe import Rpe
 
 
 def add_baroclinic_channel_tasks(component):
@@ -114,7 +114,7 @@ def add_baroclinic_channel_tasks(component):
 
         config_filename = 'baroclinic_channel.cfg'
         config = PolarisConfigParser(filepath=f'{resdir}/{config_filename}')
-        config.add_from_package('polaris.ocean.tasks.baroclinic_channel',
+        config.add_from_package('polaris.tasks.ocean.baroclinic_channel',
                                 'baroclinic_channel.cfg')
 
         init = Init(component=component, resolution=resolution, indir=resdir)
@@ -126,7 +126,7 @@ def add_baroclinic_channel_tasks(component):
         component.add_task(default)
 
         ...
-        
+
         component.add_task(Rpe(component=component, resolution=resolution,
                                indir=resdir, init=init, config=config))
 ```
@@ -140,8 +140,8 @@ added as follows:
 
 ```python
 from polaris import Task
-from polaris.ocean.tasks.baroclinic_channel.forward import Forward
-from polaris.ocean.tasks.baroclinic_channel.rpe.analysis import Analysis
+from polaris.tasks.ocean.baroclinic_channel.forward import Forward
+from polaris.tasks.ocean.baroclinic_channel.rpe.analysis import Analysis
 
 
 class Rpe(Task):
@@ -171,7 +171,7 @@ class Rpe(Task):
                 resolution=resolution, nu=nu)
 
             step.add_yaml_file(
-                'polaris.ocean.tasks.baroclinic_channel.rpe',
+                'polaris.tasks.ocean.baroclinic_channel.rpe',
                 'forward.yaml')
             self.add_step(step)
 

docs/developers_guide/framework/io.md

@@ -22,7 +22,7 @@ from polaris.io import symlink
 
 def configure(task, config):
     ...
-    with path('polaris.ocean.tasks.global_ocean.files_for_e3sm', 'README') as \
+    with path('polaris.tasks.ocean.global_ocean.files_for_e3sm', 'README') as \
             target:
         symlink(str(target), '{}/README'.format(task['work_dir']))
 ```

docs/developers_guide/framework/model.md

@@ -105,7 +105,7 @@ is located and the name of the input yaml file within that package
 as arguments to {py:meth}`polaris.ModelStep.add_yaml_file()`:
 
 ```python
-self.add_yaml_file('polaris.ocean.tasks.global_convergence.cosine_bell',
+self.add_yaml_file('polaris.tasks.ocean.global_convergence.cosine_bell',
                    'forward.yaml')
 ```
 
@@ -147,7 +147,7 @@ is located and the name of the input namelist file within that package
 as arguments to {py:meth}`polaris.ModelStep.add_namelist_file()`:
 
 ```python
-self.add_namelist_file('polaris.ocean.tasks.baroclinic_channel',
+self.add_namelist_file('polaris.tasks.ocean.baroclinic_channel',
                        'namelist.forward')
 ```
 
@@ -182,7 +182,7 @@ if nu is not None:
 # make sure output is double precision
 self.add_yaml_file('polaris.ocean.config', 'output.yaml')
 
-self.add_yaml_file('polaris.ocean.tasks.baroclinic_channel',
+self.add_yaml_file('polaris.tasks.ocean.baroclinic_channel',
                    'forward.yaml')
 
 ```
@@ -310,7 +310,7 @@ A typical streams file is added by calling
 file is located and the name of the input streams file within that package:
 
 ```python
-self.add_streams_file('polaris.ocean.tasks.baroclinic_channel',
+self.add_streams_file('polaris.tasks.ocean.baroclinic_channel',
                       'streams.forward')
 ```
 
@@ -365,7 +365,7 @@ add_streams_file(step, module, 'streams.template',
 ```
 
 In this example, taken from
-{py:class}`polaris.ocean.tasks.global_ocean.mesh.qu240.dynamic_adjustement.QU240DynamicAdjustment`,
+{py:class}`polaris.tasks.ocean.global_ocean.mesh.qu240.dynamic_adjustement.QU240DynamicAdjustment`,
 we are creating a series of steps that will be used to perform dynamic
 adjustment of the ocean model, each of which might have different durations and
 restart intervals.  Rather than creating a streams file for each step of the

docs/developers_guide/ocean/api.md

@@ -1,7 +1,7 @@
 # ocean
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean
+.. currentmodule:: polaris.tasks.ocean
 
 .. autosummary::
    :toctree: generated/
@@ -14,7 +14,7 @@
 ### baroclinic_channel
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.baroclinic_channel
+.. currentmodule:: polaris.tasks.ocean.baroclinic_channel
 
 .. autosummary::
    :toctree: generated/
@@ -56,7 +56,7 @@
 ### barotropic_gyre
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.barotropic_gyre
+.. currentmodule:: polaris.tasks.ocean.barotropic_gyre
 
 .. autosummary::
    :toctree: generated/
@@ -84,7 +84,7 @@
 ### cosine_bell
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.cosine_bell
+.. currentmodule:: polaris.tasks.ocean.cosine_bell
 
 .. autosummary::
    :toctree: generated/
@@ -121,7 +121,7 @@
 ### geostrophic
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.geostrophic
+.. currentmodule:: polaris.tasks.ocean.geostrophic
 
 .. autosummary::
    :toctree: generated/
@@ -147,7 +147,7 @@
 ### ice_shelf_2d
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.ice_shelf_2d
+.. currentmodule:: polaris.tasks.ocean.ice_shelf_2d
 
 .. autosummary::
    :toctree: generated/
@@ -173,7 +173,7 @@
 ### inertial_gravity_wave
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.inertial_gravity_wave
+.. currentmodule:: polaris.tasks.ocean.inertial_gravity_wave
 
 .. autosummary::
    :toctree: generated/
@@ -202,7 +202,7 @@
 ### internal_wave
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.internal_wave
+.. currentmodule:: polaris.tasks.ocean.internal_wave
 
 .. autosummary::
    :toctree: generated/
@@ -231,7 +231,7 @@
 ### manufactured_solution
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.manufactured_solution
+.. currentmodule:: polaris.tasks.ocean.manufactured_solution
 
 .. autosummary::
    :toctree: generated/
@@ -261,7 +261,7 @@
 ### single_column
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.single_column
+.. currentmodule:: polaris.tasks.ocean.single_column
 
 .. autosummary::
    :toctree: generated/
@@ -284,7 +284,7 @@
 ### sphere_transport
 
 ```{eval-rst}
-.. currentmodule:: polaris.ocean.tasks.sphere_transport
+.. currentmodule:: polaris.tasks.ocean.sphere_transport
 
 .. autosummary::
    :toctree: generated/

docs/developers_guide/ocean/framework.md

@@ -327,7 +327,7 @@ def add_cosine_bell_tasks(component):
                                 'convergence.cfg')
         config.add_from_package('polaris.ocean.convergence.spherical',
                                 'spherical.cfg')
-        config.add_from_package('polaris.ocean.tasks.cosine_bell',
+        config.add_from_package('polaris.tasks.ocean.cosine_bell',
                                 'cosine_bell.cfg')
 ```
 
@@ -381,7 +381,7 @@ class Forward(SphericalConvergenceForward):
         refinement_factor : float
             The factor by which to scale space, time or both
         """
-        package = 'polaris.ocean.tasks.cosine_bell'
+        package = 'polaris.tasks.ocean.cosine_bell'
         validate_vars = ['normalVelocity', 'tracer1']
         super().__init__(component=component, name=name, subdir=subdir,
                          resolution=resolution, mesh=mesh,
@@ -505,7 +505,7 @@ The `polaris.ocean.ice_shelf` module provides support for ice shelf tasks.
 
 The {py:class}`polaris.ocean.ice_shelf.IceShelf` class can serve as a parent
 class for ice shelf tests, such as
-{py:class}`polaris.ocean.tasks.ice_shelf_2d.IceShelf2d`.
+{py:class}`polaris.tasks.ocean.ice_shelf_2d.IceShelf2d`.
 
 The {py:meth}`polaris.ocean.ice_shelf.IceShelf.setup_ssh_adjustment_steps()`
 sets up `ssh_forward` and `ssh_adjustment` steps from the classes