Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve config option descriptions, names and error reporting #163

Merged
merged 6 commits into from
Aug 8, 2023
Merged

docs: improve config option descriptions, names and error reporting #163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6328f6a
fix typo
jmbuhr Jul 31, 2023
1950cef
better error reporting
jmbuhr Aug 1, 2023
1f6dfeb
fix: warn if installed entry point does not have config schema but
jmbuhr Aug 1, 2023
a4a8a46
Merge branch 'main' into docs/descriptions-and-errors
jmbuhr Aug 7, 2023
859e4c0
refactor(names): rename for consistency.
jmbuhr Aug 8, 2023
1d22131
docs(types): add custom renderer
jmbuhr Aug 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions _quarto.yml
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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