more documentation for compiling objects

Author: dwhswenson

paths_cli/compiling/_gendocs/json_type_handlers.py

@@ -146,6 +146,8 @@ def __init__(self, type_name, link_to=None):
     CategoryHandler("network"),
     CategoryHandler("strategy"),
     CategoryHandler("scheme"),
+    CategoryHandler("shooting-point-selector"),
+    CategoryHandler("interface-set"),
     EvalHandler("EvalInt"),
     EvalHandler("EvalIntStrictPos"),
     EvalHandler("EvalFloat"),

paths_cli/compiling/networks.py

@@ -2,13 +2,44 @@
     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
 )
 
-build_interface_set = InstanceCompilerPlugin(
+
+INITIAL_STATES_PARAM = Parameter(
+    'initial_states', compiler_for('volume'),
+    json_type=json_type_list(json_type_ref('volume')),
+    description="initial states for this transition",
+)
+
+
+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'), json_type=json_type_ref('cv'),
@@ -23,7 +54,8 @@
                   description=("maximum value(s) for interfaces in this"
                                "interface set")),
     ],
-    name='interface-set'
+    name='interface-set',
+    description="Interface set used in transition interface sampling.",
 )
 
 
@@ -57,15 +89,10 @@ def tis_trans_info(dct):
 
 TPS_NETWORK_PLUGIN = NetworkCompilerPlugin(
     builder=Builder('openpathsampling.TPSNetwork'),
-    parameters=[
-        Parameter('initial_states', compiler_for('volume'),
-                  json_type=json_type_list(json_type_ref('volume')),
-                  description="initial states for this transition"),
-        Parameter('final_states', compiler_for('volume'),
-                  json_type=json_type_list(json_type_ref('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)."),
 )
 
 

paths_cli/compiling/schemes.py

@@ -45,6 +45,9 @@
         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."),
 )
 
 
@@ -78,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(
@@ -87,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'])

paths_cli/compiling/shooting.py

@@ -2,14 +2,24 @@
     InstanceCompilerPlugin, CategoryCompiler, Builder, Parameter
 )
 from paths_cli.compiling.root_compiler import compiler_for
-from paths_cli.compiling.tools import custom_eval
+from paths_cli.compiling.tools import custom_eval_float
 from paths_cli.compiling.plugins import ShootingPointSelectorPlugin
+from paths_cli.compiling.json_type import json_type_ref, json_type_eval
+
+shooting_selector_compiler = compiler_for('shooting-point-selector')
+SP_SELECTOR_PARAMETER = Parameter(
+    'selector', compiler_for('shooting-point-selector'), default=None,
+    json_type=json_type_ref('shooting-point-selector'),
+    description="shooting point selection algorithm to use.",
+)
 
 
 build_uniform_selector = ShootingPointSelectorPlugin(
     builder=Builder('openpathsampling.UniformSelector'),
     parameters=[],
     name='uniform',
+    description=("Uniform shooting point selection probability: all frames "
+                 "have equal probability (endpoints excluded)."),
 )
 
 
@@ -24,11 +34,24 @@ def _remapping_gaussian_stddev(dct):
     builder=Builder('openpathsampling.GaussianBiasSelector',
                     remapper=_remapping_gaussian_stddev),
     parameters=[
-        Parameter('cv', compiler_for('cv')),
-        Parameter('mean', custom_eval),
-        Parameter('stddev', custom_eval),
+        Parameter('cv', compiler_for('cv'), json_type=json_type_ref('cv'),
+                  description="bias as a Gaussian in this CV"),
+        Parameter('mean', custom_eval_float,
+                  json_type=json_type_eval("Float"),
+                  description="mean of the Gaussian"),
+        Parameter('stddev', custom_eval_float,
+                  json_type=json_type_eval("Float"),
+                  description="standard deviation of the Gaussian"),
     ],
     name='gaussian',
+    description=(
+        "Bias shooting point selection based on a Gaussian. That is, for a "
+        "configuration :math:`x`, the probability of selecting that "
+        "configruation is proportional to "
+        r":math:`\exp(-(\lambda(x)-\bar{\lambda})^2 / (2\sigma^2))`, "
+        r"where :math:`\lambda` is the given CV, :math:`\bar{\lambda}` is "
+        r"the mean, and :math:`\sigma` is the standard deviation."
+    ),
 )
 
 

paths_cli/compiling/strategies.py

@@ -1,12 +1,10 @@
 from paths_cli.compiling.core import Builder, Parameter
-# from paths_cli.compiling.shooting import shooting_selector_compiler
 from paths_cli.compiling.plugins import (
     StrategyCompilerPlugin, CategoryPlugin
 )
 from paths_cli.compiling.root_compiler import compiler_for
 from paths_cli.compiling.json_type import json_type_ref
-
-shooting_selector_compiler = compiler_for('shooting-point-selector')
+from paths_cli.compiling.shooting import SP_SELECTOR_PARAMETER
 
 
 def _strategy_name(class_name):
@@ -19,8 +17,6 @@ def _group_parameter(group_name):
 
 
 # TODO: maybe this moves into shooting once we have the metadata?
-SP_SELECTOR_PARAMETER = Parameter('selector', shooting_selector_compiler,
-                                  default=None)
 
 ENGINE_PARAMETER = Parameter(
     'engine', compiler_for('engine'), json_type=json_type_ref('engine'),