Merge pull request #67 from dwhswenson/compile-docs

Fill in information for `compile` docs

paths_cli/compiling/_gendocs/docs_generator.py

@@ -104,7 +104,7 @@ def generate_plugin_rst(self, plugin, category_name,
             default="",
             description="name this object in order to reuse it",
         )
-        rst += self.format_parameter(name_param, type_str=" (*string*)")
+        rst += self.format_parameter(name_param, type_str=" (string)")
         for param in plugin.parameters:
             type_str = f" ({json_type_to_string(param.json_type)})"
             rst += self.format_parameter(param, type_str)

paths_cli/compiling/_gendocs/json_type_handlers.py

@@ -53,6 +53,12 @@ def _is_listof(json_type):
 )
 
 
+handle_none = JsonTypeHandler(
+    is_my_type=lambda obj: obj is None,
+    handler=lambda json_type: "type information missing",
+)
+
+
 class RefTypeHandler(JsonTypeHandler):
     """Handle JSON types of the form {"$ref": "#/definitions/..."}
 
@@ -122,18 +128,28 @@ class EvalHandler(RefTypeHandler):
         to the anchor given by ``link_to``
     """
     def __init__(self, type_name, link_to=None):
+        if link_to is None:
+            link_to = type_name
+
         super().__init__(
             type_name=type_name, def_string=type_name, link_to=link_to
         )
 
 
 JSON_TYPE_HANDLERS = [
     handle_object,
+    handle_none,
     handle_listof,
     CategoryHandler("engine"),
     CategoryHandler("cv"),
     CategoryHandler("volume"),
+    CategoryHandler("network"),
+    CategoryHandler("strategy"),
+    CategoryHandler("scheme"),
+    CategoryHandler("shooting-point-selector"),
+    CategoryHandler("interface-set"),
     EvalHandler("EvalInt"),
+    EvalHandler("EvalIntStrictPos"),
     EvalHandler("EvalFloat"),
 ]
 

paths_cli/compiling/cvs.py

@@ -1,9 +1,10 @@
 from paths_cli.compiling.core import Parameter, Builder
-from paths_cli.compiling.tools import custom_eval
+from paths_cli.compiling.tools import custom_eval, custom_eval_float
 from paths_cli.compiling.topology import build_topology
 from paths_cli.compiling.errors import InputError
 from paths_cli.utils import import_thing
 from paths_cli.compiling.plugins import CVCompilerPlugin, CategoryPlugin
+from paths_cli.compiling.json_type import json_type_eval
 
 
 class AllowedPackageHandler:
@@ -39,14 +40,17 @@ def _cv_kwargs_remapper(dct):
                                             for key, arg in kwargs.items()},
                   json_type='object', default=None,
                   description="keyword arguments for ``func``"),
-        Parameter('period_min', custom_eval, default=None,
+        Parameter('period_min', custom_eval_float, default=None,
+                  json_type=json_type_eval('Float'),
                   description=("minimum value for a periodic function, "
                                "None if not periodic")),
-        Parameter('period_max', custom_eval, default=None,
+        Parameter('period_max', custom_eval_float, default=None,
+                  json_type=json_type_eval('Float'),
                   description=("maximum value for a periodic function, "
                                "None if not periodic")),
 
     ],
+    description="Use an MDTraj analysis function to calculate a CV.",
     name="mdtraj"
 )
 

paths_cli/compiling/engines.py

@@ -3,6 +3,7 @@
 from paths_cli.compiling.core import Parameter
 from paths_cli.compiling.tools import custom_eval_int_strict_pos
 from paths_cli.compiling.plugins import EngineCompilerPlugin, CategoryPlugin
+from paths_cli.compiling.json_type import json_type_eval
 
 
 def load_openmm_xml(filename):
@@ -34,8 +35,10 @@ def _openmm_options(dct):
     Parameter('integrator', load_openmm_xml, json_type='string',
               description="XML file with the OpenMM integrator"),
     Parameter('n_steps_per_frame', custom_eval_int_strict_pos,
+              json_type=json_type_eval('IntStrictPos'),
               description="number of MD steps per saved frame"),
     Parameter("n_frames_max", custom_eval_int_strict_pos,
+              json_type=json_type_eval('IntStrictPos'),
               description=("maximum number of frames before aborting "
                            "trajectory")),
 ]

paths_cli/compiling/gendocs.py

@@ -9,6 +9,11 @@
 @click.option("--stdout", type=bool, is_flag=True, default=False)
 def main(config_file, stdout):
     """Generate documentation for installed compiling plugins."""
+    do_main(config_file, stdout)
+
+
+def do_main(config_file, stdout=False):
+    """Separate method so this can be imported and run"""
     register_installed_plugins()
     config = load_config(config_file)
     generator = DocsGenerator(config)

paths_cli/compiling/json_type.py

@@ -1,3 +1,10 @@
 
 def json_type_ref(category):
     return {"$ref": f"#/definitions/{category}_type"}
+
+def json_type_eval(check_type):
+    return {"$ref": f"#/definitions/Eval{check_type}"}
+
+def json_type_list(item_type):
+    return {'type': 'array',
+            'items': item_type}

paths_cli/compiling/networks.py

@@ -2,18 +2,60 @@
     InstanceCompilerPlugin, Builder, Parameter
 )
 from paths_cli.compiling.tools import custom_eval
-from paths_cli.compiling.plugins import NetworkCompilerPlugin, CategoryPlugin
+from paths_cli.compiling.plugins import (
+    NetworkCompilerPlugin, CategoryPlugin, InterfaceSetPlugin
+)
 from paths_cli.compiling.root_compiler import compiler_for
+from paths_cli.compiling.json_type import (
+    json_type_ref, json_type_list, json_type_eval
+)
+
+
+INITIAL_STATES_PARAM = Parameter(
+    'initial_states', compiler_for('volume'),
+    json_type=json_type_list(json_type_ref('volume')),
+    description="initial states for this transition",
+)
 
-build_interface_set = InstanceCompilerPlugin(
+
+INITIAL_STATE_PARAM = Parameter(
+    'initial_state', compiler_for('volume'),
+    json_type=json_type_list(json_type_ref('volume')),
+    description="initial state for this transition",
+)
+
+
+FINAL_STATES_PARAM = Parameter(
+    'final_states', compiler_for('volume'),
+    json_type=json_type_list(json_type_ref('volume')),
+    description="final states for this transition",
+)
+
+
+FINAL_STATE_PARAM = Parameter(
+    'final_state', compiler_for('volume'),
+    json_type=json_type_list(json_type_ref('volume')),
+    description="final state for this transition",
+)
+
+
+build_interface_set = InterfaceSetPlugin(
     builder=Builder('openpathsampling.VolumeInterfaceSet'),
     parameters=[
-        Parameter('cv', compiler_for('cv'), description="the collective "
-                  "variable for this interface set"),
-        Parameter('minvals', custom_eval),  # TODO fill in JSON types
-        Parameter('maxvals', custom_eval),  # TODO fill in JSON types
+        Parameter('cv', compiler_for('cv'), json_type=json_type_ref('cv'),
+                  description=("the collective variable for this interface "
+                               "set")),
+        Parameter('minvals', custom_eval,
+                  json_type=json_type_list(json_type_eval("Float")),
+                  description=("minimum value(s) for interfaces in this"
+                               "interface set")),
+        Parameter('maxvals', custom_eval,
+                  json_type=json_type_list(json_type_eval("Float")),
+                  description=("maximum value(s) for interfaces in this"
+                               "interface set")),
     ],
-    name='interface-set'
+    name='interface-set',
+    description="Interface set used in transition interface sampling.",
 )
 
 
@@ -47,34 +89,29 @@ def tis_trans_info(dct):
 
 TPS_NETWORK_PLUGIN = NetworkCompilerPlugin(
     builder=Builder('openpathsampling.TPSNetwork'),
-    parameters=[
-        Parameter('initial_states', compiler_for('volume'),
-                  description="initial states for this transition"),
-        Parameter('final_states', compiler_for('volume'),
-                  description="final states for this transition")
-    ],
-    name='tps'
+    parameters=[INITIAL_STATES_PARAM, FINAL_STATES_PARAM],
+    name='tps',
+    description=("Network for transition path sampling (two state TPS or "
+                 "multiple state TPS)."),
 )
 
 
-MISTIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
-    parameters=[Parameter('trans_info', mistis_trans_info)],
-    builder=Builder('openpathsampling.MISTISNetwork'),
-    name='mistis'
-)
+# MISTIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
+#     parameters=[Parameter('trans_info', mistis_trans_info)],
+#     builder=Builder('openpathsampling.MISTISNetwork'),
+#     name='mistis'
+# )
 
 
-TIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
-    builder=Builder('openpathsampling.MISTISNetwork'),
-    parameters=[Parameter('trans_info', tis_trans_info)],
-    name='tis'
-)
+# TIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
+#     builder=Builder('openpathsampling.MISTISNetwork'),
+#     parameters=[Parameter('trans_info', tis_trans_info)],
+#     name='tis'
+# )
 
 # old names not yet replaced in testing  THESE ARE WHY WE'RE DOUBLING! GET
 # RID OF THEM! (also, use an is-check)
 build_tps_network = TPS_NETWORK_PLUGIN
-build_mistis_network = MISTIS_NETWORK_PLUGIN
-build_tis_network = TIS_NETWORK_PLUGIN
 
 
 NETWORK_COMPILER = CategoryPlugin(NetworkCompilerPlugin, aliases=['networks'])

paths_cli/compiling/plugins.py

@@ -45,3 +45,11 @@ class SchemeCompilerPlugin(InstanceCompilerPlugin):
 
 class StrategyCompilerPlugin(InstanceCompilerPlugin):
     category = 'strategy'
+
+
+class ShootingPointSelectorPlugin(InstanceCompilerPlugin):
+    category = 'shooting-point-selector'
+
+
+class InterfaceSetPlugin(InstanceCompilerPlugin):
+    category = 'interface-set'

paths_cli/compiling/root_compiler.py

@@ -18,7 +18,7 @@ class CategoryCompilerRegistrationError(Exception):
     'volume',
     'state',
     'network',
-    'movescheme',
+    'scheme',
 ]
 
 COMPILE_ORDER = _DEFAULT_COMPILE_ORDER.copy()
@@ -70,8 +70,8 @@ def _get_compiler(category):
     canonical_name = _canonical_name(category)
     # create a new compiler if none exists
     if canonical_name is None:
-        canonical_name = category
-        _COMPILERS[category] = CategoryCompiler(None, category)
+        canonical_name = clean_input_key(category)
+        _COMPILERS[canonical_name] = CategoryCompiler(None, category)
     return _COMPILERS[canonical_name]
 
 

paths_cli/compiling/schemes.py

@@ -1,29 +1,53 @@
 from paths_cli.compiling.core import (
     Builder, Parameter
 )
-from paths_cli.compiling.tools import custom_eval
+from paths_cli.compiling.tools import (
+    custom_eval, custom_eval_int_strict_pos
+)
 from paths_cli.compiling.strategies import SP_SELECTOR_PARAMETER
 from paths_cli.compiling.plugins import SchemeCompilerPlugin, CategoryPlugin
 from paths_cli.compiling.root_compiler import compiler_for
+from paths_cli.compiling.json_type import (
+    json_type_ref, json_type_list, json_type_eval
+)
 
 
-NETWORK_PARAMETER = Parameter('network', compiler_for('network'))
+NETWORK_PARAMETER = Parameter(
+    'network',
+    compiler_for('network'),
+    json_type=json_type_ref('network'),
+    description="network to use with this scheme"
+)
 
-ENGINE_PARAMETER = Parameter('engine', compiler_for('engine'))  # reuse?
+ENGINE_PARAMETER = Parameter(
+    'engine', compiler_for('engine'),
+    json_type=json_type_ref('engine'),
+    description="engine to use with this scheme",
+)  # reuse?
 
 STRATEGIES_PARAMETER = Parameter('strategies', compiler_for('strategy'),
+                                 json_type=json_type_ref('strategy'),
                                  default=None)
 
 
 SPRING_SHOOTING_PLUGIN = SchemeCompilerPlugin(
     builder=Builder('openpathsampling.SpringShootingMoveScheme'),
     parameters=[
         NETWORK_PARAMETER,
-        Parameter('k_spring', custom_eval),
-        Parameter('delta_max', custom_eval),
+        Parameter('k_spring', custom_eval,
+                  json_type=json_type_eval("Float"),
+                  description="spring constant for the spring shooting move"),
+        Parameter('delta_max', custom_eval_int_strict_pos,
+                  json_type=json_type_eval("IntStrictPos"),
+                  description=("maximum shift in shooting point (number of "
+                               "frames)"),
+                  ),
         ENGINE_PARAMETER
     ],
     name='spring-shooting',
+    description=("Move scheme for TPS with the spring-shooting algorithm. "
+                 "Under most circumstances, the network provided here "
+                 "should be a 2-state TPS network."),
 )
 
 
@@ -57,6 +81,8 @@ def __call__(self, **dct):
         STRATEGIES_PARAMETER,
     ],
     name='one-way-shooting',
+    description=("One-way-shooting move scheme. This can be extended with "
+                 "additional user-defined move strategies."),
 )
 
 MOVESCHEME_PLUGIN = SchemeCompilerPlugin(
@@ -66,7 +92,11 @@ def __call__(self, **dct):
         NETWORK_PARAMETER,
         STRATEGIES_PARAMETER,
     ],
-    name='scheme'
+    name='scheme',
+    description=("Generic move scheme. Add strategies to this to make it "
+                 "useful. This defaults to a scheme that first chooses a "
+                 "move type, and then chooses the specific move within "
+                 "that type (i.e., ``OrganizeByMoveGroupStrategy``)"),
 )
 
 SCHEME_COMPILER = CategoryPlugin(SchemeCompilerPlugin, aliases=['schemes'])