Skip to content

Commit

Permalink
docs: improve config option descriptions, names and error reporting (#…
Browse files Browse the repository at this point in the history 
…163)

fix: warn if installed entry point does not have config schema but
don't crash. refs #164

refactor(names): rename for consistency.
  schema = json schema, scheme = dictionary with just pytype, description,
  defaults

docs(types): add custom renderer
  now auto-links type annotations.
  Can be removed once the feature is upstreamed in
  quartodoc

refactor(naming): change `iterations` to `max_tasks`
  and add useful description for it.

chore(docs): render
  • Loading branch information
@jmbuhr
jmbuhr authored Aug 8, 2023
1 parent e98fa09 commit 3318bdc
Show file tree
Hide file tree
Showing 83 changed files with 3,773 additions and 3,178 deletions.
5 changes: 5 additions & 0 deletions _quarto.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ website:
- _reference/runmanager.qmd
- _reference/tasks.qmd
- _reference/utils.qmd
- _reference/reaction.qmd
section: Modules
- contents:
- _reference/homolysis.reaction.Homolysis.qmd
Expand Down Expand Up @@ -102,6 +103,8 @@ interlinks:

quartodoc:
sidebar: "_sidebar.yml"
renderer:
style: _renderer.py
title: "Reference"
package: kimmdy
style: pkgdown
Expand All @@ -125,12 +128,14 @@ quartodoc:
- name: constants
- name: coordinates
- name: config
- name: schema
- name: kmc
- name: misc_helper
- name: parsing
- name: runmanager
- name: tasks
- name: utils
- name: reaction
- title: Reaction Plugins
desc: Reaction plugins bundled with KIMMDY and the protocol to add a new reaction plugin to KIMMDY
package: null
Expand Down
30 changes: 15 additions & 15 deletions _reference/changemanager.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ We should either change the name or make it do what it says it does.

#### Parameters

| Name | Type | Description | Default |
|----------------|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `recipe_steps` | list\[kimmdy.reaction.RecipeStep\] | A list of [](`~kimmdy.tasks.Task`) [](`~kimmdy.reaction.RecipeStep`) where each steps contains a `new_coords` parameter. | _required_ |
| `files` | TaskFiles | Input and output files for this [](`~kimmdy.tasks.Task`). files.input: - trr - tpr files.outputdir files.output: - trr - gro | _required_ |
| `topA` | Topology | Previous Topology | _required_ |
| `topB` | Topology | Parameter-adjusted Topology | _required_ |
| Name | Type | Description | Default |
|----------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `recipe_steps` | [list](`list`)\[[RecipeStep](`kimmdy.reaction.RecipeStep`)\] | A list of [](`~kimmdy.reaction.RecipeStep`) where each steps contains a `new_coords` parameter. | _required_ |
| `files` | [TaskFiles](`kimmdy.tasks.TaskFiles`) | Input and output files for this [](`~kimmdy.tasks.Task`). files.input: - trr - tpr files.outputdir files.output: - trr - gro | _required_ |
| `topA` | [Topology](`kimmdy.topology.topology.Topology`) | Previous Topology | _required_ |
| `topB` | [Topology](`kimmdy.topology.topology.Topology`) | Parameter-adjusted Topology | _required_ |

### modify_plumed { #kimmdy.changemanager.modify_plumed }

Expand All @@ -52,9 +52,9 @@ TODO: finish this function.

#### Parameters

| Name | Type | Description | Default |
|----------------|------------------------------------|--------------------------------------------------------------------|------------|
| `recipe_steps` | list\[kimmdy.reaction.RecipeStep\] | A list of [RecipeStep](`~kimmdy.reaction.RecipeStep`)s. parameter. | _required_ |
| Name | Type | Description | Default |
|----------------|--------------------------------------------------------------|----------------------------------------------------------|------------|
| `recipe_steps` | [list](`list`)\[[RecipeStep](`kimmdy.reaction.RecipeStep`)\] | A list of [](`~kimmdy.reaction.RecipeStep`)s. parameter. | _required_ |

### modify_top { #kimmdy.changemanager.modify_top }

Expand All @@ -67,9 +67,9 @@ to a file to be used by external programs (gromacs).

#### Parameters

| Name | Type | Description | Default |
|----------------|------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|------------|
| `recipe_steps` | list\[kimmdy.reaction.RecipeStep\] | A list of [RecipeStep](``kimmdy.reaction.RecipeStep``)s. parameter. | _required_ |
| `files` | TaskFiles | Input and output files for this [Task](``kimmdy.tasks.Task``). files.input: - top files.output: - top | _required_ |
| `ffpatch` | typing.Optional\[pathlib.Path\] | TODO: deprecate | _required_ |
| `topology` | typing.Optional\[kimmdy.topology.topology.Topology\] | TODO: make this required instead of optional | _required_ |
| Name | Type | Description | Default |
|----------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|------------|
| `recipe_steps` | [list](`list`)\[[RecipeStep](`kimmdy.reaction.RecipeStep`)\] | A list of [](`~kimmdy.reaction.RecipeStep`)s. parameter. | _required_ |
| `files` | [TaskFiles](`kimmdy.tasks.TaskFiles`) | Input and output files for this [](`~kimmdy.tasks.Task`). files.input: - top files.output: - top | _required_ |
| `ffpatch` | [Optional](`typing.Optional`)\[[Path](`pathlib.Path`)\] | TODO: deprecate | _required_ |
| `topology` | [Optional](`typing.Optional`)\[[Topology](`kimmdy.topology.topology.Topology`)\] | TODO: make this required instead of optional | _required_ |
54 changes: 37 additions & 17 deletions _reference/cmd.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,19 @@ Also initialized logging and configuration.

| Name | Description |
| --- | --- |
| [build_examples](#kimmdy.cmd.build_examples) | Build examples from the command line. |
| [configure_logging](#kimmdy.cmd.configure_logging) | Configure logging. |
| [get_build_example_args](#kimmdy.cmd.get_build_example_args) | Parse command line arguments. |
| [get_cmdline_args](#kimmdy.cmd.get_cmdline_args) | Parse command line arguments and configure logger. |
| [kimmdy](#kimmdy.cmd.kimmdy) | Run KIMMDY from the command line. |
| [kimmdy_run](#kimmdy.cmd.kimmdy_run) | Run KIMMDY from python. |

### build_examples { #kimmdy.cmd.build_examples }

`cmd.build_examples()`

Build examples from the command line.

### configure_logging { #kimmdy.cmd.configure_logging }

`cmd.configure_logging(args, color=False)`
Expand All @@ -25,10 +33,22 @@ for the terminal.

#### Parameters

| Name | Type | Description | Default |
|---------|--------------------|-----------------------------------------------------------|------------|
| `args` | argparse.Namespace | Command line arguments. | _required_ |
| `color` | | Should logging output use colorcodes for terminal output? | `False` |
| Name | Type | Description | Default |
|---------|----------------------------------------------------------|-----------------------------------------------------------|------------|
| `args` | [argparse](`argparse`).[Namespace](`argparse.Namespace`) | Command line arguments. | _required_ |
| `color` | | Should logging output use colorcodes for terminal output? | `False` |

### get_build_example_args { #kimmdy.cmd.get_build_example_args }

`cmd.get_build_example_args()`

Parse command line arguments.

#### Returns

| Type | Description |
|--------------------------|-------------------------------|
| [Namespace](`Namespace`) | parsed command line arguments |

### get_cmdline_args { #kimmdy.cmd.get_cmdline_args }

Expand All @@ -38,9 +58,9 @@ Parse command line arguments and configure logger.

#### Returns

| Type | Description |
|-----------|-------------------------------|
| Namespace | parsed command line arguments |
| Type | Description |
|--------------------------|-------------------------------|
| [Namespace](`Namespace`) | parsed command line arguments |

### kimmdy { #kimmdy.cmd.kimmdy }

Expand All @@ -60,16 +80,16 @@ Run KIMMDY from python.
TODO: The concat option looks like we probably
want an additional kimmdy analysis module,
maybe with its own subcommand(s)?
Like gromacs ``gmx <command>``?
Like gromacs ``gmx &lt;command&gt;``?

#### Parameters

| Name | Type | Description | Default |
|--------------------|--------|-------------------------------------------------------------------------------------------|----------------------|
| `input` | Path | kimmdy input yml file. | `Path('kimmdy.yml')` |
| `loglevel` | str | Loglevel. One of ["INFO", "WARNING", "MESSAGE", "DEBUG"] | `'DEBUG'` |
| `logfile` | Path | File path of the logfile. | `Path('kimmdy.log')` |
| `checkpoint` | str | File path if a kimmdy.cpt file to restart KIMMDY from a checkpoint. | `''` |
| `concat` | bool | Don't perform a full KIMMDY run but instead concatenate trajectories from a previous run. | `False` |
| `show_plugins` | bool | Show available plugins and exit. | `False` |
| `show_schema_path` | bool | Print path to yaml schema for use with yaml-language-server e.g. in VSCode and Neovim | `False` |
| Name | Type | Description | Default |
|--------------------|------------------------|-------------------------------------------------------------------------------------------|----------------------|
| `input` | [Path](`pathlib.Path`) | kimmdy input yml file. | `Path('kimmdy.yml')` |
| `loglevel` | [str](`str`) | Loglevel. One of ["INFO", "WARNING", "MESSAGE", "DEBUG"] | `'DEBUG'` |
| `logfile` | [Path](`pathlib.Path`) | File path of the logfile. | `Path('kimmdy.log')` |
| `checkpoint` | [str](`str`) | File path if a kimmdy.cpt file to restart KIMMDY from a checkpoint. | `''` |
| `concat` | [bool](`bool`) | Don't perform a full KIMMDY run but instead concatenate trajectories from a previous run. | `False` |
| `show_plugins` | [bool](`bool`) | Show available plugins and exit. | `False` |
| `show_schema_path` | [bool](`bool`) | Print path to yaml schema for use with yaml-language-server e.g. in VSCode and Neovim | `False` |
12 changes: 6 additions & 6 deletions _reference/config.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,12 @@ and computationally expensive operations.

#### Parameters

| Name | Type | Description | Default |
|------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `input_file` | pathlib.Path \| None | Path to the config yaml file. | `None` |
| `recursive_dict` | dict \| None | For internal use only, used in reading settings in recursively. | `None` |
| `scheme` | dict \| None | dict containing types and defaults for casting and validating settings. | `None` |
| `section` | str | current section e.g. to determine the level of recursion in nested configs e.g. "config", "config.mds" or "config.reactions.homolysis" | `'config'` |
| Name | Type | Description | Default |
|------------------|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `input_file` | [Path](`pathlib.Path`) \| None | Path to the config yaml file. | `None` |
| `recursive_dict` | [dict](`dict`) \| None | For internal use only, used in reading settings in recursively. | `None` |
| `scheme` | [dict](`dict`) \| None | dict containing types and defaults for casting and validating settings. | `None` |
| `section` | [str](`str`) | current section e.g. to determine the level of recursion in nested configs e.g. "config", "config.mds" or "config.reactions.homolysis" | `'config'` |

#### Methods

Expand Down
34 changes: 31 additions & 3 deletions _reference/coordinates.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,44 @@

`coordinates`

TODO: WIP

## Functions

| Name | Description |
| --- | --- |
| [get_explicit_MultipleDihedrals](#kimmdy.coordinates.get_explicit_MultipleDihedrals) | Takes a valid dihedral key and returns explicit |
| [get_explicit_or_type](#kimmdy.coordinates.get_explicit_or_type) | Takes an Interaction and associated key, InteractionTypes, Topology |
| [is_parameterized](#kimmdy.coordinates.is_parameterized) | Parameterized topology entries have c0 and c1 attributes != None |
| [merge_dihedrals](#kimmdy.coordinates.merge_dihedrals) | Merge one to two Dihedrals or -Types into a Dihedral in free-energy syntax |
| [merge_top_parameter_growth](#kimmdy.coordinates.merge_top_parameter_growth) | Takes two Topologies and joins them for a smooth free-energy like parameter transition simulation |

### get_explicit_MultipleDihedrals { #kimmdy.coordinates.get_explicit_MultipleDihedrals }

`coordinates.get_explicit_MultipleDihedrals(dihedral_key, top, dihedrals_in, periodicity_max=6)`

Takes a valid dihedral key and returns explicit
dihedral parameters for a given topology

### get_explicit_or_type { #kimmdy.coordinates.get_explicit_or_type }

`coordinates.get_explicit_or_type(key, interaction, interaction_types, top, periodicity='')`

Takes an Interaction and associated key, InteractionTypes, Topology
and Periodicity (for dihedrals) and returns an object with the parameters of this Interaction

### is_parameterized { #kimmdy.coordinates.is_parameterized }

`coordinates.is_parameterized(entry)`

Parameterized topology entries have c0 and c1 attributes != None
Parameterized topology entries have c0 and c1 attributes != None

### merge_dihedrals { #kimmdy.coordinates.merge_dihedrals }

`coordinates.merge_dihedrals(dihedral_key, interactionA, interactionB, interaction_typesA, interaction_typesB, topA, topB, funct, periodicity)`

Merge one to two Dihedrals or -Types into a Dihedral in free-energy syntax

### merge_top_parameter_growth { #kimmdy.coordinates.merge_top_parameter_growth }

`coordinates.merge_top_parameter_growth(topA, topB, focus_nr=None)`

Takes two Topologies and joins them for a smooth free-energy like parameter transition simulation
8 changes: 5 additions & 3 deletions _reference/index.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,16 @@ Modules
| --- | --- |
| [changemanager](changemanager.qmd#kimmdy.changemanager) | The changemanager module holds functions that modify the system |
| [constants](constants.qmd#kimmdy.constants) | Comstants used throughout KIMMDY |
| [coordinates](coordinates.qmd#kimmdy.coordinates) | TODO: WIP |
| [coordinates](coordinates.qmd#kimmdy.coordinates) | |
| [config](config.qmd#kimmdy.config) | Read and validate kimmdy.yml configuration files |
| [schema](schema.qmd#kimmdy.schema) | Handle the schema for the config file. |
| [kmc](kmc.qmd#kimmdy.kmc) | Kinetic Monte Carlo (KMC) classes and functions. |
| [misc_helper](misc_helper.qmd#kimmdy.misc_helper) | Miscelaneous utilitiies that didn't fit anywhere else for now. |
| [parsing](parsing.qmd#kimmdy.parsing) | All read_<...> and write_<...> functions. |
| [misc_helper](misc_helper.qmd#kimmdy.misc_helper) | Miscelaneous utilitiies that didn&#x27;t fit anywhere else for now. |
| [parsing](parsing.qmd#kimmdy.parsing) | All read_&lt;...&gt; and write_&lt;...&gt; functions. |
| [runmanager](runmanager.qmd#kimmdy.runmanager) | The Runmanager is the main entry point of the program. |
| [tasks](tasks.qmd#kimmdy.tasks) | |
| [utils](utils.qmd#kimmdy.utils) | |
| [reaction](reaction.qmd#kimmdy.reaction) | ReactionPlugin protocoll and reaction recipes. |

## Reaction Plugins

Expand Down
Loading

0 comments on commit 3318bdc

Please sign in to comment.