Skip to content

Commit f9cd13d

Browse files
dwhswensondwhswenson
authored
Merge pull request #67 from dwhswenson/compile-docs
Fill in information for `compile` docs
2 parents 539c8b0 + a74d29d commit f9cd13d

File tree

15 files changed

+271
-71
lines changed

15 files changed

+271
-71
lines changed

‎paths_cli/compiling/_gendocs/docs_generator.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ def generate_plugin_rst(self, plugin, category_name,
104104
default="",
105105
description="name this object in order to reuse it",
106106
)
107-
rst += self.format_parameter(name_param, type_str=" (*string*)")
107+
rst += self.format_parameter(name_param, type_str=" (string)")
108108
for param in plugin.parameters:
109109
type_str = f" ({json_type_to_string(param.json_type)})"
110110
rst += self.format_parameter(param, type_str)

‎paths_cli/compiling/_gendocs/json_type_handlers.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,12 @@ def _is_listof(json_type):
5353
)
5454

5555

56+
handle_none = JsonTypeHandler(
57+
is_my_type=lambda obj: obj is None,
58+
handler=lambda json_type: "type information missing",
59+
)
60+
61+
5662
class RefTypeHandler(JsonTypeHandler):
5763
"""Handle JSON types of the form {"$ref": "#/definitions/..."}
5864
@@ -122,18 +128,28 @@ class EvalHandler(RefTypeHandler):
122128
to the anchor given by ``link_to``
123129
"""
124130
def __init__(self, type_name, link_to=None):
131+
if link_to is None:
132+
link_to = type_name
133+
125134
super().__init__(
126135
type_name=type_name, def_string=type_name, link_to=link_to
127136
)
128137

129138

130139
JSON_TYPE_HANDLERS = [
131140
handle_object,
141+
handle_none,
132142
handle_listof,
133143
CategoryHandler("engine"),
134144
CategoryHandler("cv"),
135145
CategoryHandler("volume"),
146+
CategoryHandler("network"),
147+
CategoryHandler("strategy"),
148+
CategoryHandler("scheme"),
149+
CategoryHandler("shooting-point-selector"),
150+
CategoryHandler("interface-set"),
136151
EvalHandler("EvalInt"),
152+
EvalHandler("EvalIntStrictPos"),
137153
EvalHandler("EvalFloat"),
138154
]
139155

‎paths_cli/compiling/cvs.py‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
from paths_cli.compiling.core import Parameter, Builder
2-
from paths_cli.compiling.tools import custom_eval
2+
from paths_cli.compiling.tools import custom_eval, custom_eval_float
33
from paths_cli.compiling.topology import build_topology
44
from paths_cli.compiling.errors import InputError
55
from paths_cli.utils import import_thing
66
from paths_cli.compiling.plugins import CVCompilerPlugin, CategoryPlugin
7+
from paths_cli.compiling.json_type import json_type_eval
78

89

910
class AllowedPackageHandler:
@@ -39,14 +40,17 @@ def _cv_kwargs_remapper(dct):
3940
for key, arg in kwargs.items()},
4041
json_type='object', default=None,
4142
description="keyword arguments for ``func``"),
42-
Parameter('period_min', custom_eval, default=None,
43+
Parameter('period_min', custom_eval_float, default=None,
44+
json_type=json_type_eval('Float'),
4345
description=("minimum value for a periodic function, "
4446
"None if not periodic")),
45-
Parameter('period_max', custom_eval, default=None,
47+
Parameter('period_max', custom_eval_float, default=None,
48+
json_type=json_type_eval('Float'),
4649
description=("maximum value for a periodic function, "
4750
"None if not periodic")),
4851

4952
],
53+
description="Use an MDTraj analysis function to calculate a CV.",
5054
name="mdtraj"
5155
)
5256

‎paths_cli/compiling/engines.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
from paths_cli.compiling.core import Parameter
44
from paths_cli.compiling.tools import custom_eval_int_strict_pos
55
from paths_cli.compiling.plugins import EngineCompilerPlugin, CategoryPlugin
6+
from paths_cli.compiling.json_type import json_type_eval
67

78

89
def load_openmm_xml(filename):
@@ -34,8 +35,10 @@ def _openmm_options(dct):
3435
Parameter('integrator', load_openmm_xml, json_type='string',
3536
description="XML file with the OpenMM integrator"),
3637
Parameter('n_steps_per_frame', custom_eval_int_strict_pos,
38+
json_type=json_type_eval('IntStrictPos'),
3739
description="number of MD steps per saved frame"),
3840
Parameter("n_frames_max", custom_eval_int_strict_pos,
41+
json_type=json_type_eval('IntStrictPos'),
3942
description=("maximum number of frames before aborting "
4043
"trajectory")),
4144
]

‎paths_cli/compiling/gendocs.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@
99
@click.option("--stdout", type=bool, is_flag=True, default=False)
1010
def main(config_file, stdout):
1111
"""Generate documentation for installed compiling plugins."""
12+
do_main(config_file, stdout)
13+
14+
15+
def do_main(config_file, stdout=False):
16+
"""Separate method so this can be imported and run"""
1217
register_installed_plugins()
1318
config = load_config(config_file)
1419
generator = DocsGenerator(config)

‎paths_cli/compiling/json_type.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
11

22
def json_type_ref(category):
33
return {"$ref": f"#/definitions/{category}_type"}
4+
5+
def json_type_eval(check_type):
6+
return {"$ref": f"#/definitions/Eval{check_type}"}
7+
8+
def json_type_list(item_type):
9+
return {'type': 'array',
10+
'items': item_type}

‎paths_cli/compiling/networks.py‎

Lines changed: 63 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,60 @@
22
InstanceCompilerPlugin, Builder, Parameter
33
)
44
from paths_cli.compiling.tools import custom_eval
5-
from paths_cli.compiling.plugins import NetworkCompilerPlugin, CategoryPlugin
5+
from paths_cli.compiling.plugins import (
6+
NetworkCompilerPlugin, CategoryPlugin, InterfaceSetPlugin
7+
)
68
from paths_cli.compiling.root_compiler import compiler_for
9+
from paths_cli.compiling.json_type import (
10+
json_type_ref, json_type_list, json_type_eval
11+
)
12+
13+
14+
INITIAL_STATES_PARAM = Parameter(
15+
'initial_states', compiler_for('volume'),
16+
json_type=json_type_list(json_type_ref('volume')),
17+
description="initial states for this transition",
18+
)
719

8-
build_interface_set = InstanceCompilerPlugin(
20+
21+
INITIAL_STATE_PARAM = Parameter(
22+
'initial_state', compiler_for('volume'),
23+
json_type=json_type_list(json_type_ref('volume')),
24+
description="initial state for this transition",
25+
)
26+
27+
28+
FINAL_STATES_PARAM = Parameter(
29+
'final_states', compiler_for('volume'),
30+
json_type=json_type_list(json_type_ref('volume')),
31+
description="final states for this transition",
32+
)
33+
34+
35+
FINAL_STATE_PARAM = Parameter(
36+
'final_state', compiler_for('volume'),
37+
json_type=json_type_list(json_type_ref('volume')),
38+
description="final state for this transition",
39+
)
40+
41+
42+
build_interface_set = InterfaceSetPlugin(
943
builder=Builder('openpathsampling.VolumeInterfaceSet'),
1044
parameters=[
11-
Parameter('cv', compiler_for('cv'), description="the collective "
12-
"variable for this interface set"),
13-
Parameter('minvals', custom_eval), # TODO fill in JSON types
14-
Parameter('maxvals', custom_eval), # TODO fill in JSON types
45+
Parameter('cv', compiler_for('cv'), json_type=json_type_ref('cv'),
46+
description=("the collective variable for this interface "
47+
"set")),
48+
Parameter('minvals', custom_eval,
49+
json_type=json_type_list(json_type_eval("Float")),
50+
description=("minimum value(s) for interfaces in this"
51+
"interface set")),
52+
Parameter('maxvals', custom_eval,
53+
json_type=json_type_list(json_type_eval("Float")),
54+
description=("maximum value(s) for interfaces in this"
55+
"interface set")),
1556
],
16-
name='interface-set'
57+
name='interface-set',
58+
description="Interface set used in transition interface sampling.",
1759
)
1860

1961

@@ -47,34 +89,29 @@ def tis_trans_info(dct):
4789

4890
TPS_NETWORK_PLUGIN = NetworkCompilerPlugin(
4991
builder=Builder('openpathsampling.TPSNetwork'),
50-
parameters=[
51-
Parameter('initial_states', compiler_for('volume'),
52-
description="initial states for this transition"),
53-
Parameter('final_states', compiler_for('volume'),
54-
description="final states for this transition")
55-
],
56-
name='tps'
92+
parameters=[INITIAL_STATES_PARAM, FINAL_STATES_PARAM],
93+
name='tps',
94+
description=("Network for transition path sampling (two state TPS or "
95+
"multiple state TPS)."),
5796
)
5897

5998

60-
MISTIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
61-
parameters=[Parameter('trans_info', mistis_trans_info)],
62-
builder=Builder('openpathsampling.MISTISNetwork'),
63-
name='mistis'
64-
)
99+
# MISTIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
100+
# parameters=[Parameter('trans_info', mistis_trans_info)],
101+
# builder=Builder('openpathsampling.MISTISNetwork'),
102+
# name='mistis'
103+
# )
65104

66105

67-
TIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
68-
builder=Builder('openpathsampling.MISTISNetwork'),
69-
parameters=[Parameter('trans_info', tis_trans_info)],
70-
name='tis'
71-
)
106+
# TIS_NETWORK_PLUGIN = NetworkCompilerPlugin(
107+
# builder=Builder('openpathsampling.MISTISNetwork'),
108+
# parameters=[Parameter('trans_info', tis_trans_info)],
109+
# name='tis'
110+
# )
72111

73112
# old names not yet replaced in testing THESE ARE WHY WE'RE DOUBLING! GET
74113
# RID OF THEM! (also, use an is-check)
75114
build_tps_network = TPS_NETWORK_PLUGIN
76-
build_mistis_network = MISTIS_NETWORK_PLUGIN
77-
build_tis_network = TIS_NETWORK_PLUGIN
78115

79116

80117
NETWORK_COMPILER = CategoryPlugin(NetworkCompilerPlugin, aliases=['networks'])

‎paths_cli/compiling/plugins.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,11 @@ class SchemeCompilerPlugin(InstanceCompilerPlugin):
4545

4646
class StrategyCompilerPlugin(InstanceCompilerPlugin):
4747
category = 'strategy'
48+
49+
50+
class ShootingPointSelectorPlugin(InstanceCompilerPlugin):
51+
category = 'shooting-point-selector'
52+
53+
54+
class InterfaceSetPlugin(InstanceCompilerPlugin):
55+
category = 'interface-set'

‎paths_cli/compiling/root_compiler.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ class CategoryCompilerRegistrationError(Exception):
1818
'volume',
1919
'state',
2020
'network',
21-
'movescheme',
21+
'scheme',
2222
]
2323

2424
COMPILE_ORDER = _DEFAULT_COMPILE_ORDER.copy()
@@ -70,8 +70,8 @@ def _get_compiler(category):
7070
canonical_name = _canonical_name(category)
7171
# create a new compiler if none exists
7272
if canonical_name is None:
73-
canonical_name = category
74-
_COMPILERS[category] = CategoryCompiler(None, category)
73+
canonical_name = clean_input_key(category)
74+
_COMPILERS[canonical_name] = CategoryCompiler(None, category)
7575
return _COMPILERS[canonical_name]
7676

7777

‎paths_cli/compiling/schemes.py‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,53 @@
11
from paths_cli.compiling.core import (
22
Builder, Parameter
33
)
4-
from paths_cli.compiling.tools import custom_eval
4+
from paths_cli.compiling.tools import (
5+
custom_eval, custom_eval_int_strict_pos
6+
)
57
from paths_cli.compiling.strategies import SP_SELECTOR_PARAMETER
68
from paths_cli.compiling.plugins import SchemeCompilerPlugin, CategoryPlugin
79
from paths_cli.compiling.root_compiler import compiler_for
10+
from paths_cli.compiling.json_type import (
11+
json_type_ref, json_type_list, json_type_eval
12+
)
813

914

10-
NETWORK_PARAMETER = Parameter('network', compiler_for('network'))
15+
NETWORK_PARAMETER = Parameter(
16+
'network',
17+
compiler_for('network'),
18+
json_type=json_type_ref('network'),
19+
description="network to use with this scheme"
20+
)
1121

12-
ENGINE_PARAMETER = Parameter('engine', compiler_for('engine')) # reuse?
22+
ENGINE_PARAMETER = Parameter(
23+
'engine', compiler_for('engine'),
24+
json_type=json_type_ref('engine'),
25+
description="engine to use with this scheme",
26+
) # reuse?
1327

1428
STRATEGIES_PARAMETER = Parameter('strategies', compiler_for('strategy'),
29+
json_type=json_type_ref('strategy'),
1530
default=None)
1631

1732

1833
SPRING_SHOOTING_PLUGIN = SchemeCompilerPlugin(
1934
builder=Builder('openpathsampling.SpringShootingMoveScheme'),
2035
parameters=[
2136
NETWORK_PARAMETER,
22-
Parameter('k_spring', custom_eval),
23-
Parameter('delta_max', custom_eval),
37+
Parameter('k_spring', custom_eval,
38+
json_type=json_type_eval("Float"),
39+
description="spring constant for the spring shooting move"),
40+
Parameter('delta_max', custom_eval_int_strict_pos,
41+
json_type=json_type_eval("IntStrictPos"),
42+
description=("maximum shift in shooting point (number of "
43+
"frames)"),
44+
),
2445
ENGINE_PARAMETER
2546
],
2647
name='spring-shooting',
48+
description=("Move scheme for TPS with the spring-shooting algorithm. "
49+
"Under most circumstances, the network provided here "
50+
"should be a 2-state TPS network."),
2751
)
2852

2953

@@ -57,6 +81,8 @@ def __call__(self, **dct):
5781
STRATEGIES_PARAMETER,
5882
],
5983
name='one-way-shooting',
84+
description=("One-way-shooting move scheme. This can be extended with "
85+
"additional user-defined move strategies."),
6086
)
6187

6288
MOVESCHEME_PLUGIN = SchemeCompilerPlugin(
@@ -66,7 +92,11 @@ def __call__(self, **dct):
6692
NETWORK_PARAMETER,
6793
STRATEGIES_PARAMETER,
6894
],
69-
name='scheme'
95+
name='scheme',
96+
description=("Generic move scheme. Add strategies to this to make it "
97+
"useful. This defaults to a scheme that first chooses a "
98+
"move type, and then chooses the specific move within "
99+
"that type (i.e., ``OrganizeByMoveGroupStrategy``)"),
70100
)
71101

72102
SCHEME_COMPILER = CategoryPlugin(SchemeCompilerPlugin, aliases=['schemes'])

0 commit comments

Comments
 (0)