From 2ef5fd78f6d8ed567e25cbef12655e157b65d710 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 27 Jul 2023 12:15:07 +1000 Subject: [PATCH 01/28] Basic flowchart for cookbook --- docs/_static/css/deflist-flowchart.css | 162 +++++++++++++++++++++++++ docs/conf.py | 1 + docs/cookbook/index.rst | 71 +++++++++++ 3 files changed, 234 insertions(+) create mode 100644 docs/_static/css/deflist-flowchart.css diff --git a/docs/_static/css/deflist-flowchart.css b/docs/_static/css/deflist-flowchart.css new file mode 100644 index 000000000..d6b6fe424 --- /dev/null +++ b/docs/_static/css/deflist-flowchart.css @@ -0,0 +1,162 @@ +:root { + --arrow-thickness: 4px; + --arrow-head-size: 7px; + --arrow-length: 2em; + --arrow-color: var(--pst-color-text-muted); + --deflist-def-bg-color: var(--pst-color-surface); +} +.arrow.thick { + --arrow-thickness: 6px; + --arrow-head-size: 10px; +} + +.deflist-flowchart p:first-child { + margin-top: 0; +} + +.deflist-flowchart p:last-child { + margin-bottom: 0; +} + +.deflist-flowchart { + margin: 1em 0; +} + +.deflist-flowchart li, +.deflist-flowchart li ul +{ + margin: 0; + padding: 0; +} + +.deflist-flowchart ul, +ul.deflist-flowchart { + display: flex; + flex-direction: column; + justify-content: space-between; + height: 100%; + grid-column-gap: 1em; + margin: 0; + padding: 0; +} + +.deflist-flowchart li { + list-style: none; +} + +.deflist-flowchart .arrow-down, +.deflist-flowchart .arrow-up, +.deflist-flowchart .arrow-cycle { + display: block; + min-height: var(--arrow-length); + height: 100%; + margin: 0.75em auto; + width: fit-content; + position: relative; + z-index: 1; +} + +.deflist-flowchart .arrow-down::after, +.deflist-flowchart .arrow-up::after, +.deflist-flowchart .arrow-cycle::after, +.deflist-flowchart .arrow-cycle::before +{ + --actual-arrow-length: max(var(--arrow-length), 100%); + height: calc(var(--actual-arrow-length)/1.4142); + width: auto; + aspect-ratio: 1; + content: ""; + padding: 0; + display: inline-block; + transform: rotate(45deg); + background-image: + linear-gradient( + 45deg, + transparent calc(50% - var(--arrow-thickness)/2), + var(--arrow-color) calc(50% - var(--arrow-thickness)/2), + var(--arrow-color) calc(50% + var(--arrow-thickness)/2), + transparent calc(50% + var(--arrow-thickness)/2) + ), + linear-gradient( + -45deg, + var(--arrow-color) var(--arrow-head-size), + transparent var(--arrow-head-size) + ); + position: absolute; + top: 0; + left: 50%; + transform-origin: 0 0; + z-index: -1; +} + +.deflist-flowchart .arrow-cycle::after, +.deflist-flowchart .arrow-cycle::before +{ + margin: 0 calc(-0.5 * var(--arrow-length)/1.4142 + 10px); + margin-top: calc(var(--arrow-length) / 7); +} + +.deflist-flowchart .arrow-up::after, +.deflist-flowchart .arrow-cycle::before +{ + transform: rotate(-135deg); +} + + +.deflist-flowchart dl { + text-align: center; + position: relative; + border: 1px solid var(--pst-color-border); + border-radius: .25rem; + padding: 0.5em; + margin: 0.5em 0; +} + +.deflist-flowchart dl dl { + background-color: var(--deflist-def-bg-color); + border-radius: 4px; + box-shadow: 0 6px 10px 0 rgba(0,0,0,0.14), + 0 1px 18px 0 rgba(0,0,0,0.12), + 0 3px 5px -1px rgba(0,0,0,0.4); +} + +.deflist-flowchart .optional dl { + box-shadow: 0 2px 2px 0 rgba(0,0,0,0.14),0 1px 5px 0 rgba(0,0,0,0.12),0 3px 1px -2px rgba(0,0,0,0.2); +} + +.deflist-flowchart dd { + margin: 0; + margin-top: 0.5em; + padding: 0; +} + +.deflist-flowchart dl a { + font-weight: bold; +} + +.deflist-flowchart .flowchart-sidebyside, .deflist-flowchart div.flowchart-sidebyside > ul:only-child { + display: grid; + grid-auto-columns: minmax(0, 1fr); + grid-auto-flow: column; +} + +.deflist-flowchart .optional { + --arrow-color: #777; + border: 1.5px var(--arrow-color) dashed; + border-radius: 10px; + padding: 1em !important; + filter: opacity(0.5); + transition: filter 0.2s; +} + +.deflist-flowchart .optional::before { + content: "[Optional]"; + text-align: center; + font-size: 0.8em; + line-height: 0; + font-weight: 200; +} + +.deflist-flowchart .optional:hover { + filter: opacity(1.0); +} diff --git a/docs/conf.py b/docs/conf.py index 6bd299063..55dcae28e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -127,6 +127,7 @@ html_css_files = [ "css/custom.css", "css/custom-api.css", + "css/deflist-flowchart.css", ] # custom-api.css is compiled from custom-api.scss diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index df7406ed1..73baf091e 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -3,6 +3,77 @@ Cookbook This will include various how-to guides. +.. container:: deflist-flowchart + + * Setup + - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + + .. rst-class:: arrow-down + - :any:`Loading Molecules` + + - Component + A component of a chemical system. + + - .. container:: flowchart-sidebyside + + - + - :class:`openfe.SmallMoleculeComponent` + Small molecule components describe the ligands that will be mutated. + + - .. container:: flowchart-sidebyside + + - + - + .. rst-class:: arrow-down + - + + - + - + .. rst-class:: arrow-down + - :any:`Creating Atom Mappings` + + - Mapping + Mapping between atoms in a mutation. + + .. rst-class:: arrow-down + - + + - LigandNetwork + A network of mutations between the provided ligands. + + .. rst-class:: arrow-down + - + + - + - :class:`openfe.SmallMoleculeComponent`, :class:`openfe.SolventComponent`, :class:`openfe.ProteinComponent` + All components are included in the ChemicalSystem + + .. rst-class:: arrow-down + - + + - ChemicalSystem + A description of the system that each ligand lives in. + + .. rst-class:: arrow-down + - + + - AlchemicNetwork + Combining chemical systems for each ligand with a network that describes how to mutate between them yields a complete description of a simulation campaign. + + .. rst-class:: arrow-down + * + + * Run + Def + + .. rst-class:: arrow-down + * + + * Gather + Def + + .. toctree:: loading_molecules From 59159f84340286a300446a69ac0c8ec1ac2734a8 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 10 Aug 2023 12:35:54 +1000 Subject: [PATCH 02/28] Improve flowchart --- docs/_static/css/deflist-flowchart.css | 79 +++++++++---------- docs/cookbook/index.rst | 19 +++-- .../reference/api/alchemical_data_objects.rst | 2 + docs/reference/api/ligand_network.rst | 1 - 4 files changed, 49 insertions(+), 52 deletions(-) diff --git a/docs/_static/css/deflist-flowchart.css b/docs/_static/css/deflist-flowchart.css index d6b6fe424..b4fdad135 100644 --- a/docs/_static/css/deflist-flowchart.css +++ b/docs/_static/css/deflist-flowchart.css @@ -54,6 +54,7 @@ ul.deflist-flowchart { width: fit-content; position: relative; z-index: 1; + text-shadow: var(--pst-color-background) 0 0 10px; } .deflist-flowchart .arrow-down::after, @@ -99,35 +100,48 @@ ul.deflist-flowchart { .deflist-flowchart .arrow-up::after, .deflist-flowchart .arrow-cycle::before { - transform: rotate(-135deg); + transform: rotate(-135deg); } - .deflist-flowchart dl { - text-align: center; - position: relative; - border: 1px solid var(--pst-color-border); - border-radius: .25rem; - padding: 0.5em; - margin: 0.5em 0; -} - -.deflist-flowchart dl dl { - background-color: var(--deflist-def-bg-color); - border-radius: 4px; - box-shadow: 0 6px 10px 0 rgba(0,0,0,0.14), - 0 1px 18px 0 rgba(0,0,0,0.12), - 0 3px 5px -1px rgba(0,0,0,0.4); + display: flex; + flex-direction: row-reverse; + margin: 0; } - -.deflist-flowchart .optional dl { - box-shadow: 0 2px 2px 0 rgba(0,0,0,0.14),0 1px 5px 0 rgba(0,0,0,0.12),0 3px 1px -2px rgba(0,0,0,0.2); +.deflist-flowchart dt { + display: inline-block; + writing-mode: vertical-rl; + margin-top: .25rem; + flex-grow: 0; } - .deflist-flowchart dd { + text-align: center; + position: relative; + border: 1px solid var(--pst-color-border); + border-radius: .25rem; + padding: 0.5em; margin: 0; - margin-top: 0.5em; - padding: 0; + display: inline-block; + flex-grow: 1; +} + +.deflist-flowchart dd dl { + background-color: var(--deflist-def-bg-color); + border-radius: 4px; + box-shadow: 0 6px 10px 0 rgba(0,0,0,0.14), + 0 1px 18px 0 rgba(0,0,0,0.12), + 0 3px 5px -1px rgba(0,0,0,0.4); + display: block; + margin: 0.5em 0; +} +.deflist-flowchart dd dt { + writing-mode: horizontal-tb; + display: block; + margin-top: 0; +} +.deflist-flowchart dd dd { + border: none; + display: block; } .deflist-flowchart dl a { @@ -139,24 +153,3 @@ ul.deflist-flowchart { grid-auto-columns: minmax(0, 1fr); grid-auto-flow: column; } - -.deflist-flowchart .optional { - --arrow-color: #777; - border: 1.5px var(--arrow-color) dashed; - border-radius: 10px; - padding: 1em !important; - filter: opacity(0.5); - transition: filter 0.2s; -} - -.deflist-flowchart .optional::before { - content: "[Optional]"; - text-align: center; - font-size: 0.8em; - line-height: 0; - font-weight: 200; -} - -.deflist-flowchart .optional:hover { - filter: opacity(1.0); -} diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 73baf091e..dbc9a8bf3 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -3,6 +3,9 @@ Cookbook This will include various how-to guides. +.. module:: openfe + :noindex: + .. container:: deflist-flowchart * Setup @@ -18,7 +21,7 @@ This will include various how-to guides. - .. container:: flowchart-sidebyside - - - :class:`openfe.SmallMoleculeComponent` + - :class:`SmallMoleculeComponent` Small molecule components describe the ligands that will be mutated. - .. container:: flowchart-sidebyside @@ -33,33 +36,33 @@ This will include various how-to guides. .. rst-class:: arrow-down - :any:`Creating Atom Mappings` - - Mapping - Mapping between atoms in a mutation. + - :class:`LigandAtomMapping` + Mapping between atoms in one small molecule and those in another for a single transformation (network edge). .. rst-class:: arrow-down - - - LigandNetwork + - :class:`LigandNetwork` A network of mutations between the provided ligands. .. rst-class:: arrow-down - - - - :class:`openfe.SmallMoleculeComponent`, :class:`openfe.SolventComponent`, :class:`openfe.ProteinComponent` + - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` All components are included in the ChemicalSystem .. rst-class:: arrow-down - - - ChemicalSystem + - :class:`ChemicalSystem` A description of the system that each ligand lives in. .. rst-class:: arrow-down - - - AlchemicNetwork - Combining chemical systems for each ligand with a network that describes how to mutate between them yields a complete description of a simulation campaign. + - :class:`AlchemicalNetwork` + A complete description of a simulation campaign, including the :class:`LigandNetwork` and a :class:`ChemicalSystem` for each ligand. .. rst-class:: arrow-down * diff --git a/docs/reference/api/alchemical_data_objects.rst b/docs/reference/api/alchemical_data_objects.rst index 1cc641b2f..734f8350e 100644 --- a/docs/reference/api/alchemical_data_objects.rst +++ b/docs/reference/api/alchemical_data_objects.rst @@ -35,6 +35,8 @@ Tools for mapping atoms in one molecule to those in another. Used to generate ef LigandAtomMapper LigandAtomMapping +.. autoclass:: openfe.LigandNetwork + Alchemical Simulations ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/reference/api/ligand_network.rst b/docs/reference/api/ligand_network.rst index 58089db77..09c294db8 100644 --- a/docs/reference/api/ligand_network.rst +++ b/docs/reference/api/ligand_network.rst @@ -15,7 +15,6 @@ Atom Mappers LomapAtomMapper PersesAtomMapper - Scorers ------- From 7019be792acc689b82cbbdb179f33a0c8cc4552b Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 10 Aug 2023 13:28:01 +1000 Subject: [PATCH 03/28] Fix warnings --- docs/conf.py | 1 + .../reference/api/alchemical_data_objects.rst | 21 +++++---------- docs/reference/api/openmm_rfe.rst | 27 +++++++------------ openfe/setup/ligand_network.py | 2 +- 4 files changed, 19 insertions(+), 32 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 55dcae28e..5ba9932e5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -70,6 +70,7 @@ autodoc_default_options = { "members": True, "member-order": "bysource", + "inherited-members": "GufeTokenizable,BaseModel" } toc_object_entries_show_parents = "hide" diff --git a/docs/reference/api/alchemical_data_objects.rst b/docs/reference/api/alchemical_data_objects.rst index 734f8350e..925975074 100644 --- a/docs/reference/api/alchemical_data_objects.rst +++ b/docs/reference/api/alchemical_data_objects.rst @@ -11,8 +11,8 @@ We describe a chemical system as being made up of one or more "components," e.g. :noindex: .. autosummary:: - :nosignatures: - :toctree: generated/ + :nosignatures: + :toctree: generated/ SmallMoleculeComponent ProteinComponent @@ -25,17 +25,13 @@ Atom Mappings Tools for mapping atoms in one molecule to those in another. Used to generate efficient ligand networks. -.. module:: openfe - :noindex: - .. autosummary:: - :nosignatures: - :toctree: generated/ + :nosignatures: + :toctree: generated/ LigandAtomMapper LigandAtomMapping - -.. autoclass:: openfe.LigandNetwork + LigandNetwork Alchemical Simulations @@ -43,12 +39,9 @@ Alchemical Simulations Descriptions of anticipated alchemical simulation campaigns. -.. module:: openfe - :noindex: - .. autosummary:: - :nosignatures: - :toctree: generated/ + :nosignatures: + :toctree: generated/ Transformation AlchemicalNetwork diff --git a/docs/reference/api/openmm_rfe.rst b/docs/reference/api/openmm_rfe.rst index 20e34a902..e8b222c08 100644 --- a/docs/reference/api/openmm_rfe.rst +++ b/docs/reference/api/openmm_rfe.rst @@ -4,8 +4,18 @@ OpenMM Relative Free Energy Protocol This section provides details about the OpenMM Relative Free Energy Protocol implemented in OpenFE. +Protocol API specification +-------------------------- + .. module:: openfe.protocols.openmm_rfe +.. autosummary:: + :nosignatures: + :toctree: generated/ + + RelativeHybridTopologyProtocol + RelativeHybridTopologyProtocolResult + Protocol Settings ----------------- @@ -124,20 +134,3 @@ Below are the settings which can be tweaked in the protocol. The default setting :field-list-validators: False :inherited-members: SettingsBaseModel :member-order: bysource - -Protocol API specification --------------------------- - -.. module:: openfe.protocols.openmm_rfe - :noindex: - -.. autoclass:: RelativeHybridTopologyProtocol - :no-members: - - .. automethod:: default_settings - - .. automethod:: create - - .. automethod:: gather - -.. autoclass:: RelativeHybridTopologyProtocolResult diff --git a/openfe/setup/ligand_network.py b/openfe/setup/ligand_network.py index 948fd6a60..081aee144 100644 --- a/openfe/setup/ligand_network.py +++ b/openfe/setup/ligand_network.py @@ -162,7 +162,7 @@ def enlarge_graph(self, *, edges=None, nodes=None) -> LigandNetwork: Returns ------- - :class:`.Network : + :class:`.Network` : a new network adding the given edges and nodes to this network """ if edges is None: From 737c68c8e6880758b9370f5757fde894ca393532 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 10 Aug 2023 14:09:00 +1000 Subject: [PATCH 04/28] Center content on flowchart arrows --- docs/_static/css/deflist-flowchart.css | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/_static/css/deflist-flowchart.css b/docs/_static/css/deflist-flowchart.css index b4fdad135..5e9090ce0 100644 --- a/docs/_static/css/deflist-flowchart.css +++ b/docs/_static/css/deflist-flowchart.css @@ -47,7 +47,9 @@ ul.deflist-flowchart { .deflist-flowchart .arrow-down, .deflist-flowchart .arrow-up, .deflist-flowchart .arrow-cycle { - display: block; + display: flex; + justify-content: center; + align-items: center; min-height: var(--arrow-length); height: 100%; margin: 0.75em auto; @@ -55,8 +57,20 @@ ul.deflist-flowchart { position: relative; z-index: 1; text-shadow: var(--pst-color-background) 0 0 10px; + padding: 0; +} + +.deflist-flowchart .arrow-down, +.deflist-flowchart .arrow-cycle { + padding-bottom: var(--arrow-head-size); +} + +.deflist-flowchart .arrow-up, +.deflist-flowchart .arrow-cycle { + padding-top: var(--arrow-head-size); } + .deflist-flowchart .arrow-down::after, .deflist-flowchart .arrow-up::after, .deflist-flowchart .arrow-cycle::after, From d0a5acc13195eb7d206a836756425b300a0b3065 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 10 Aug 2023 17:32:37 +1000 Subject: [PATCH 05/28] Rework flowchart to reflect lowest level --- docs/_sass/deflist-flowchart.scss | 181 +++++++++++++++++++++++++ docs/_static/css/deflist-flowchart.css | 169 ----------------------- docs/cookbook/index.rst | 68 +++++----- docs/cookbook/loading_molecules.rst | 1 + 4 files changed, 218 insertions(+), 201 deletions(-) create mode 100644 docs/_sass/deflist-flowchart.scss delete mode 100644 docs/_static/css/deflist-flowchart.css diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss new file mode 100644 index 000000000..98f563c90 --- /dev/null +++ b/docs/_sass/deflist-flowchart.scss @@ -0,0 +1,181 @@ +:root { + --arrow-thickness: 4px; + --arrow-head-size: 7px; + --arrow-length: 2em; + --arrow-color: var(--pst-color-text-muted); + --deflist-def-bg-color: var(--pst-color-surface); +} +.arrow.thick { + --arrow-thickness: 6px; + --arrow-head-size: 10px; +} + +.deflist-flowchart ul, +ul.deflist-flowchart { + display: flex; + flex-direction: column; + justify-content: space-between; + height: 100%; + grid-column-gap: 1em; + margin: 0; + padding: 0; +} + +.deflist-flowchart { + margin: 1em 0; + + p:first-child { + margin-top: 0; + } + + p:last-child { + margin-bottom: 0; + } + + li, + li ul + { + margin: 0; + padding: 0; + } + + li:empty:not([class]) + { + display: None; + } + + li { + list-style: none; + } + + .arrow-down, + .arrow-up, + .arrow-cycle { + display: flex; + justify-content: center; + align-items: center; + min-height: var(--arrow-length); + height: 100%; + margin: 0.75em auto; + width: fit-content; + position: relative; + z-index: 1; + text-shadow: var(--pst-color-background) 0 0 10px; + padding: 0; + } + + .arrow-down, + .arrow-cycle { + padding-bottom: var(--arrow-head-size); + } + + .arrow-up, + .arrow-cycle { + padding-top: var(--arrow-head-size); + } + + + .arrow-down::after, + .arrow-up::after, + .arrow-cycle::after, + .arrow-cycle::before + { + --actual-arrow-length: max(var(--arrow-length), 100%); + height: calc(var(--actual-arrow-length)/1.4142); + width: auto; + aspect-ratio: 1; + content: ""; + padding: 0; + display: inline-block; + transform: rotate(45deg); + background-image: + linear-gradient( + 45deg, + transparent calc(50% - var(--arrow-thickness)/2), + var(--arrow-color) calc(50% - var(--arrow-thickness)/2), + var(--arrow-color) calc(50% + var(--arrow-thickness)/2), + transparent calc(50% + var(--arrow-thickness)/2) + ), + linear-gradient( + -45deg, + var(--arrow-color) var(--arrow-head-size), + transparent var(--arrow-head-size) + ); + position: absolute; + top: 0; + left: 50%; + transform-origin: 0 0; + z-index: -1; + } + + .arrow-cycle::after, + .arrow-cycle::before + { + margin: 0 calc(-0.5 * var(--arrow-length)/1.4142 + 10px); + margin-top: calc(var(--arrow-length) / 7); + } + + .arrow-up::after, + .arrow-cycle::before + { + transform: rotate(-135deg); + } + + dl { + display: flex; + flex-direction: row-reverse; + margin: 0; + } + dt { + display: inline-block; + writing-mode: vertical-rl; + margin-top: .25rem; + flex-grow: 0; + } + dd { + text-align: center; + position: relative; + border: 1px solid var(--pst-color-border); + border-radius: .25rem; + padding: 0.5em; + margin: 0; + display: inline-block; + flex-grow: 1; + } + + dd dl { + background-color: var(--deflist-def-bg-color); + border-radius: 4px; + box-shadow: 0 6px 10px 0 rgba(0,0,0,0.14), + 0 1px 18px 0 rgba(0,0,0,0.12), + 0 3px 5px -1px rgba(0,0,0,0.4); + display: block; + margin: 0.5em 0; + } + dd dt { + writing-mode: horizontal-tb; + display: block; + margin-top: 0; + } + dd dd { + border: none; + display: block; + } + + dl a { + font-weight: bold; + } + + .flowchart-sidebyside, div.flowchart-sidebyside > ul:only-child { + display: flex; + flex-direction: row; + flex-wrap: nowrap; + > .flowchart-narrow { + flex: 0; + min-width: 200px; + } + > * { + flex: 1; + } + } +} \ No newline at end of file diff --git a/docs/_static/css/deflist-flowchart.css b/docs/_static/css/deflist-flowchart.css deleted file mode 100644 index 5e9090ce0..000000000 --- a/docs/_static/css/deflist-flowchart.css +++ /dev/null @@ -1,169 +0,0 @@ -:root { - --arrow-thickness: 4px; - --arrow-head-size: 7px; - --arrow-length: 2em; - --arrow-color: var(--pst-color-text-muted); - --deflist-def-bg-color: var(--pst-color-surface); -} -.arrow.thick { - --arrow-thickness: 6px; - --arrow-head-size: 10px; -} - -.deflist-flowchart p:first-child { - margin-top: 0; -} - -.deflist-flowchart p:last-child { - margin-bottom: 0; -} - -.deflist-flowchart { - margin: 1em 0; -} - -.deflist-flowchart li, -.deflist-flowchart li ul -{ - margin: 0; - padding: 0; -} - -.deflist-flowchart ul, -ul.deflist-flowchart { - display: flex; - flex-direction: column; - justify-content: space-between; - height: 100%; - grid-column-gap: 1em; - margin: 0; - padding: 0; -} - -.deflist-flowchart li { - list-style: none; -} - -.deflist-flowchart .arrow-down, -.deflist-flowchart .arrow-up, -.deflist-flowchart .arrow-cycle { - display: flex; - justify-content: center; - align-items: center; - min-height: var(--arrow-length); - height: 100%; - margin: 0.75em auto; - width: fit-content; - position: relative; - z-index: 1; - text-shadow: var(--pst-color-background) 0 0 10px; - padding: 0; -} - -.deflist-flowchart .arrow-down, -.deflist-flowchart .arrow-cycle { - padding-bottom: var(--arrow-head-size); -} - -.deflist-flowchart .arrow-up, -.deflist-flowchart .arrow-cycle { - padding-top: var(--arrow-head-size); -} - - -.deflist-flowchart .arrow-down::after, -.deflist-flowchart .arrow-up::after, -.deflist-flowchart .arrow-cycle::after, -.deflist-flowchart .arrow-cycle::before -{ - --actual-arrow-length: max(var(--arrow-length), 100%); - height: calc(var(--actual-arrow-length)/1.4142); - width: auto; - aspect-ratio: 1; - content: ""; - padding: 0; - display: inline-block; - transform: rotate(45deg); - background-image: - linear-gradient( - 45deg, - transparent calc(50% - var(--arrow-thickness)/2), - var(--arrow-color) calc(50% - var(--arrow-thickness)/2), - var(--arrow-color) calc(50% + var(--arrow-thickness)/2), - transparent calc(50% + var(--arrow-thickness)/2) - ), - linear-gradient( - -45deg, - var(--arrow-color) var(--arrow-head-size), - transparent var(--arrow-head-size) - ); - position: absolute; - top: 0; - left: 50%; - transform-origin: 0 0; - z-index: -1; -} - -.deflist-flowchart .arrow-cycle::after, -.deflist-flowchart .arrow-cycle::before -{ - margin: 0 calc(-0.5 * var(--arrow-length)/1.4142 + 10px); - margin-top: calc(var(--arrow-length) / 7); -} - -.deflist-flowchart .arrow-up::after, -.deflist-flowchart .arrow-cycle::before -{ - transform: rotate(-135deg); -} - -.deflist-flowchart dl { - display: flex; - flex-direction: row-reverse; - margin: 0; -} -.deflist-flowchart dt { - display: inline-block; - writing-mode: vertical-rl; - margin-top: .25rem; - flex-grow: 0; -} -.deflist-flowchart dd { - text-align: center; - position: relative; - border: 1px solid var(--pst-color-border); - border-radius: .25rem; - padding: 0.5em; - margin: 0; - display: inline-block; - flex-grow: 1; -} - -.deflist-flowchart dd dl { - background-color: var(--deflist-def-bg-color); - border-radius: 4px; - box-shadow: 0 6px 10px 0 rgba(0,0,0,0.14), - 0 1px 18px 0 rgba(0,0,0,0.12), - 0 3px 5px -1px rgba(0,0,0,0.4); - display: block; - margin: 0.5em 0; -} -.deflist-flowchart dd dt { - writing-mode: horizontal-tb; - display: block; - margin-top: 0; -} -.deflist-flowchart dd dd { - border: none; - display: block; -} - -.deflist-flowchart dl a { - font-weight: bold; -} - -.deflist-flowchart .flowchart-sidebyside, .deflist-flowchart div.flowchart-sidebyside > ul:only-child { - display: grid; - grid-auto-columns: minmax(0, 1fr); - grid-auto-flow: column; -} diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index dbc9a8bf3..ea1040b43 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -9,57 +9,59 @@ This will include various how-to guides. .. container:: deflist-flowchart * Setup - - Chemical component definition - SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + - .. container:: flowchart-sidebyside - .. rst-class:: arrow-down - - :any:`Loading Molecules` + - - - Component - A component of a chemical system. + .. rst-class:: flowchart-narrow + - - :class:`Protocol` + Simulation procedure for an alchemic mutation. - - .. container:: flowchart-sidebyside + .. rst-class:: arrow-down + - - - - - :class:`SmallMoleculeComponent` - Small molecule components describe the ligands that will be mutated. + - - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + + .. rst-class:: arrow-down + - :any:`Loading Molecules` + + - Component + A component of a chemical system. - .. container:: flowchart-sidebyside - - - - - .. rst-class:: arrow-down - - + - - :class:`SmallMoleculeComponent` + Small molecule components describe the ligands that will be mutated. - - - - .. rst-class:: arrow-down - :any:`Creating Atom Mappings` - :class:`LigandAtomMapping` - Mapping between atoms in one small molecule and those in another for a single transformation (network edge). + Corresponds atoms in one small molecule to those in another. .. rst-class:: arrow-down - - - :class:`LigandNetwork` - A network of mutations between the provided ligands. + - + - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` + All components are included in the ChemicalSystem - .. rst-class:: arrow-down - - + .. rst-class:: arrow-down + - :any:`Assembling into ChemicalSystems` - - - - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` - All components are included in the ChemicalSystem + - :class:`ChemicalSystem` + The complete system of chemical components required to simulate a given transformation target. - .. rst-class:: arrow-down - - + .. rst-class:: arrow-down + - - - :class:`ChemicalSystem` - A description of the system that each ligand lives in. + - :class:`Transformation` + A single transformation + + .. rst-class:: arrow-down + - - .. rst-class:: arrow-down - - - :class:`AlchemicalNetwork` A complete description of a simulation campaign, including the :class:`LigandNetwork` and a :class:`ChemicalSystem` for each ligand. @@ -68,13 +70,15 @@ This will include various how-to guides. * * Run - Def + - term + def .. rst-class:: arrow-down * * Gather - Def + - term + def .. toctree:: diff --git a/docs/cookbook/loading_molecules.rst b/docs/cookbook/loading_molecules.rst index a22a6d1ae..205225f81 100644 --- a/docs/cookbook/loading_molecules.rst +++ b/docs/cookbook/loading_molecules.rst @@ -98,6 +98,7 @@ can be freely defined. solv = openfe.SolventComponent(ion_concentation=0.15 * unit.molar) +.. _Assembling into ChemicalSystems: Assembling into ChemicalSystems ------------------------------- From 05c074cf1b0b0db45038fc42b26186c60751c364 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 12:17:12 +1000 Subject: [PATCH 06/28] More flowcharts --- docs/_sass/deflist-flowchart.scss | 30 ++- docs/cookbook/index.rst | 208 ++++++++++++++++-- docs/cookbook/loading_molecules.rst | 4 + .../api/alchemical_network_planning.rst | 2 + docs/reference/api/ligand_network.rst | 8 +- 5 files changed, 227 insertions(+), 25 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 98f563c90..1067319f1 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -77,6 +77,8 @@ ul.deflist-flowchart { .arrow-down::after, .arrow-up::after, + .arrow-multiple.arrow-down::before, + .arrow-multiple.arrow-up::before, .arrow-cycle::after, .arrow-cycle::before { @@ -108,19 +110,33 @@ ul.deflist-flowchart { z-index: -1; } - .arrow-cycle::after, - .arrow-cycle::before - { - margin: 0 calc(-0.5 * var(--arrow-length)/1.4142 + 10px); - margin-top: calc(var(--arrow-length) / 7); + .arrow-cycle, .arrow-multiple { + &::after { + translate: 10px 0; + } + &::before { + translate: -10px 0; + } } .arrow-up::after, + .arrow-multiple.arrow-up::before, .arrow-cycle::before { transform: rotate(-135deg); } + .arrow-cycle::before { + translate: -10px calc(var(--actual-arrow-length) + 2 * var(--arrow-head-size)); + } + + .arrow-aside { + margin-left: calc(8 * var(--arrow-head-size)); + &::after { + left: calc(-4 * var(--arrow-head-size)); + } + } + dl { display: flex; flex-direction: row-reverse; @@ -178,4 +194,8 @@ ul.deflist-flowchart { flex: 1; } } + + .flowchart-spacer { + height: 99999% + } } \ No newline at end of file diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index ea1040b43..bec308442 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -6,6 +6,10 @@ This will include various how-to guides. .. module:: openfe :noindex: +Basic Workflow +-------------- + + .. container:: deflist-flowchart * Setup @@ -14,7 +18,177 @@ This will include various how-to guides. - .. rst-class:: flowchart-narrow - - - :class:`Protocol` + - - + .. rst-class:: flowchart-spacer + - + + - :class:`Protocol` + Simulation procedure for an alchemic mutation. + + .. rst-class:: arrow-down + - + + - - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + + - .. container:: flowchart-sidebyside + + - + .. rst-class:: flowchart-narrow + - - + + .. rst-class:: arrow-down + - :any:`Loading small molecules` + + - :class:`SmallMoleculeComponent` + Small molecule components describe the ligands that will be mutated. + + .. rst-class:: arrow-down arrow-downright arrow-multiple + - + + - - .. container:: flowchart-sidebyside + + - - + + .. rst-class:: arrow-down + - :any:`Defining solvents` + + - :class:`SolventComponent` + Small molecule components describe the ligands that will be mutated. + + .. rst-class:: arrow-down + - + + - - + + .. rst-class:: arrow-down + - :any:`Loading proteins` + + - :class:`ProteinComponent` + Small molecule components describe the ligands that will be mutated. + + .. rst-class:: arrow-down + - + + - :class:`ChemicalSystem` + The complete system of chemical components required to simulate a given transformation target. + + .. rst-class:: arrow-down + - + + - :any:`Alchemical Network Planning` + Classes to plan a simulation campaign. + + .. rst-class:: arrow-down + - + + - :class:`AlchemicalNetwork` + A complete description of a simulation campaign, consisting of a collection of :class:`Transformation` objects and a :class:`ChemicalSystem` for each ligand the transformations connect. + + .. rst-class:: arrow-down + * + + * Run + - term + def + + .. rst-class:: arrow-down + * + + * Gather + - term + def + +Network-First Workflow +----------------------------- + +.. container:: deflist-flowchart + + * Setup + - .. container:: flowchart-sidebyside + + - + .. rst-class:: flowchart-narrow + - + - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` + All components are included in the ChemicalSystem + + .. rst-class:: arrow-down + - :any:`Assembling into ChemicalSystems` + + - :class:`ChemicalSystem` + The complete system of chemical components required to simulate a given transformation target. + + .. rst-class:: arrow-down arrow-multiple + - + + - - .. container:: flowchart-sidebyside + + - - :class:`SmallMoleculeComponent` + Small molecule components describe the ligands that will be mutated. + + + .. rst-class:: arrow-down arrow-multiple + - + + - - :class:`LigandAtomMapper` + Generates atom maps between one molecule and another. + + .. rst-class:: arrow-down + - + + - - + .. rst-class:: flowchart-spacer + - + - :any:`Atom Map Scorers` + Objective function for optimization of a ligand network. + + .. rst-class:: arrow-down + - + + - :mod:`openfe.setup.ligand_network_planning` + Functions to plan a network of ligand mutations given a :class:`LigandAtomMapper` and a scorer. + + .. rst-class:: arrow-down + - + + - :class:`LigandNetwork` + A network of ligand transformations. + + .. rst-class:: arrow-down + - + + - + - + .. rst-class:: flowchart-spacer + - + + - :class:`Protocol` + Simulation procedure for an alchemic mutation. + + .. rst-class:: arrow-down + - + + - :class:`AlchemicalNetwork` + A complete simulation campaign. + + +Transformation-First Workflow +----------------------------- + +.. container:: deflist-flowchart + + * Setup + - .. container:: flowchart-sidebyside + + - + + .. rst-class:: flowchart-narrow + - - + .. rst-class:: flowchart-spacer + - + + - :class:`Protocol` Simulation procedure for an alchemic mutation. .. rst-class:: arrow-down @@ -34,8 +208,20 @@ This will include various how-to guides. - - :class:`SmallMoleculeComponent` Small molecule components describe the ligands that will be mutated. - .. rst-class:: arrow-down - - :any:`Creating Atom Mappings` + - .. container:: flowchart-sidebyside + + - - + .. rst-class:: arrow-down arrow-multiple + - + + - :class:`LigandNetwork` + + .. rst-class:: arrow-down arrow-multiple + - + + - - + .. rst-class:: arrow-down + - :any:`Creating Atom Mappings` - :class:`LigandAtomMapping` Corresponds atoms in one small molecule to those in another. @@ -64,21 +250,7 @@ This will include various how-to guides. - :class:`AlchemicalNetwork` - A complete description of a simulation campaign, including the :class:`LigandNetwork` and a :class:`ChemicalSystem` for each ligand. - - .. rst-class:: arrow-down - * - - * Run - - term - def - - .. rst-class:: arrow-down - * - - * Gather - - term - def + A complete description of a simulation campaign, consisting of a collection of :class:`Transformation` objects and a :class:`ChemicalSystem` for each ligand the transformations connect. .. toctree:: diff --git a/docs/cookbook/loading_molecules.rst b/docs/cookbook/loading_molecules.rst index 205225f81..698763437 100644 --- a/docs/cookbook/loading_molecules.rst +++ b/docs/cookbook/loading_molecules.rst @@ -24,6 +24,8 @@ We will walk through how different items can be loaded, and then how these are assembled to form ``ChemicalSystem`` objects. +.. _Loading small molecules: + Loading small molecules ----------------------- @@ -59,6 +61,7 @@ As these types of structures are typically stored inside sdf files, there is a ` To load multiple molcules, use RDKit's ``Chem.SDMolSupplier`` to iterate over the contents, and create a ``SmallMoleculeComponent`` from each. +.. _Loading proteins: Loading proteins ---------------- @@ -78,6 +81,7 @@ To load a protein, use the :func:`openfe.ProteinComponent.from_pdb_file` or :fun p = openfe.ProteinComponent.from_pdb_file('file.pdb') +.. _Defining solvents: Defining solvents ----------------- diff --git a/docs/reference/api/alchemical_network_planning.rst b/docs/reference/api/alchemical_network_planning.rst index a1167be4c..b8e18431f 100644 --- a/docs/reference/api/alchemical_network_planning.rst +++ b/docs/reference/api/alchemical_network_planning.rst @@ -1,3 +1,5 @@ +.. _Alchemical Network Planning: + Alchemical Network Planning =========================== diff --git a/docs/reference/api/ligand_network.rst b/docs/reference/api/ligand_network.rst index 09c294db8..1b4b82a29 100644 --- a/docs/reference/api/ligand_network.rst +++ b/docs/reference/api/ligand_network.rst @@ -15,8 +15,10 @@ Atom Mappers LomapAtomMapper PersesAtomMapper -Scorers -------- +.. _Atom Map Scorers: + +Atom Map Scorers +---------------- LOMAP Scorers ~~~~~~~~~~~~~ @@ -57,6 +59,8 @@ PersesScorers default_perses_scorer +.. _Ligand Network Planners: + Network Planners ---------------- From de34d067ecab55ae362a3c6426896ef4654c25bc Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 13:06:00 +1000 Subject: [PATCH 07/28] Initial arrow-combine prototype --- docs/_sass/deflist-flowchart.scss | 116 ++++++++++++++++++++---------- docs/cookbook/index.rst | 37 ++++++---- 2 files changed, 103 insertions(+), 50 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 1067319f1..43f401b49 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -48,9 +48,19 @@ ul.deflist-flowchart { list-style: none; } + .arrow-down::after, + .arrow-up::after, + .arrow-multiple.arrow-down::before, + .arrow-multiple.arrow-up::before, + .arrow-cycle::after, + .arrow-cycle::before { + content: ""; + } + .arrow-down, .arrow-up, - .arrow-cycle { + .arrow-cycle + { display: flex; justify-content: center; align-items: center; @@ -62,6 +72,45 @@ ul.deflist-flowchart { z-index: 1; text-shadow: var(--pst-color-background) 0 0 10px; padding: 0; + + &::before, &::after { + --actual-arrow-length: max(var(--arrow-length), 100%); + --arrow-tail-gradient: + linear-gradient( + 45deg, + transparent calc(50% - var(--arrow-thickness)/2), + var(--arrow-color) calc(50% - var(--arrow-thickness)/2), + var(--arrow-color) calc(50% + var(--arrow-thickness)/2), + transparent calc(50% + var(--arrow-thickness)/2) + ); + --arrow-head-gradient: + linear-gradient( + -45deg, + var(--arrow-color) var(--arrow-head-size), + transparent var(--arrow-head-size) + ); + height: calc(var(--actual-arrow-length)/1.4142); + width: auto; + aspect-ratio: 1; + padding: 0; + display: inline-block; + transform: rotate(45deg); + background-image: + var(--arrow-tail-gradient), + var(--arrow-head-gradient); + position: absolute; + top: 0; + left: 50%; + transform-origin: 0 0; + z-index: -1; + } + + &.arrow-tail { + &::before, &::after { + background-image: + var(--arrow-tail-gradient); + } + } } .arrow-down, @@ -74,42 +123,6 @@ ul.deflist-flowchart { padding-top: var(--arrow-head-size); } - - .arrow-down::after, - .arrow-up::after, - .arrow-multiple.arrow-down::before, - .arrow-multiple.arrow-up::before, - .arrow-cycle::after, - .arrow-cycle::before - { - --actual-arrow-length: max(var(--arrow-length), 100%); - height: calc(var(--actual-arrow-length)/1.4142); - width: auto; - aspect-ratio: 1; - content: ""; - padding: 0; - display: inline-block; - transform: rotate(45deg); - background-image: - linear-gradient( - 45deg, - transparent calc(50% - var(--arrow-thickness)/2), - var(--arrow-color) calc(50% - var(--arrow-thickness)/2), - var(--arrow-color) calc(50% + var(--arrow-thickness)/2), - transparent calc(50% + var(--arrow-thickness)/2) - ), - linear-gradient( - -45deg, - var(--arrow-color) var(--arrow-head-size), - transparent var(--arrow-head-size) - ); - position: absolute; - top: 0; - left: 50%; - transform-origin: 0 0; - z-index: -1; - } - .arrow-cycle, .arrow-multiple { &::after { translate: 10px 0; @@ -127,7 +140,7 @@ ul.deflist-flowchart { } .arrow-cycle::before { - translate: -10px calc(var(--actual-arrow-length) + 2 * var(--arrow-head-size)); + translate: -10px var(--actual-arrow-length); } .arrow-aside { @@ -136,6 +149,33 @@ ul.deflist-flowchart { left: calc(-4 * var(--arrow-head-size)); } } + + .arrow-tail { + &.arrow-down { + margin-bottom: 0; + } + &.arrow-up { + margin-top: 0; + } + } + + .arrow-head { + &.arrow-up { + margin-bottom: 0; + } + &.arrow-down { + margin-top: 0; + } + } + + + .arrow-combine::before { + background: var(--arrow-color); + height: var(--arrow-thickness); + display: block; + content: ""; + margin: calc(-0.5 * var(--arrow-thickness)) 20px; + } dl { display: flex; diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index bec308442..67198cebc 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -119,7 +119,7 @@ Network-First Workflow - :class:`ChemicalSystem` The complete system of chemical components required to simulate a given transformation target. - .. rst-class:: arrow-down arrow-multiple + .. rst-class:: arrow-down arrow-multiple arrow-tail - - - .. container:: flowchart-sidebyside @@ -128,13 +128,13 @@ Network-First Workflow Small molecule components describe the ligands that will be mutated. - .. rst-class:: arrow-down arrow-multiple + .. rst-class:: arrow-down arrow-multiple arrow-tail - - - :class:`LigandAtomMapper` Generates atom maps between one molecule and another. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - - - @@ -143,19 +143,19 @@ Network-First Workflow - :any:`Atom Map Scorers` Objective function for optimization of a ligand network. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - - - :mod:`openfe.setup.ligand_network_planning` - Functions to plan a network of ligand mutations given a :class:`LigandAtomMapper` and a scorer. + .. rst-class:: arrow-combine + - - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-head - - :class:`LigandNetwork` A network of ligand transformations. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - - @@ -166,9 +166,16 @@ Network-First Workflow - :class:`Protocol` Simulation procedure for an alchemic mutation. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - + + .. rst-class:: arrow-combine + - + + .. rst-class:: arrow-down arrow-head + - + - :class:`AlchemicalNetwork` A complete simulation campaign. @@ -191,7 +198,7 @@ Transformation-First Workflow - :class:`Protocol` Simulation procedure for an alchemic mutation. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - - - Chemical component definition @@ -226,7 +233,7 @@ Transformation-First Workflow - :class:`LigandAtomMapping` Corresponds atoms in one small molecule to those in another. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - - @@ -239,9 +246,15 @@ Transformation-First Workflow - :class:`ChemicalSystem` The complete system of chemical components required to simulate a given transformation target. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - + .. rst-class:: arrow-combine + - + + .. rst-class:: arrow-down arrow-head + - + - :class:`Transformation` A single transformation From 0dbc7d9df9640fc0653aa296581c69772fc466a9 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 14:17:07 +1000 Subject: [PATCH 08/28] Nice combined arrows --- docs/_sass/deflist-flowchart.scss | 57 +++++++++++++++++++++++++------ docs/cookbook/index.rst | 30 ++++++---------- 2 files changed, 56 insertions(+), 31 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 43f401b49..26c430d60 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -4,6 +4,8 @@ --arrow-length: 2em; --arrow-color: var(--pst-color-text-muted); --deflist-def-bg-color: var(--pst-color-surface); + --arrow-multiple-gap: 20px; + --flowchart-column-gap: 16px; } .arrow.thick { --arrow-thickness: 6px; @@ -16,7 +18,7 @@ ul.deflist-flowchart { flex-direction: column; justify-content: space-between; height: 100%; - grid-column-gap: 1em; + grid-column-gap: var(--flowchart-column-gap); margin: 0; padding: 0; } @@ -66,8 +68,8 @@ ul.deflist-flowchart { align-items: center; min-height: var(--arrow-length); height: 100%; + width: 100%; margin: 0.75em auto; - width: fit-content; position: relative; z-index: 1; text-shadow: var(--pst-color-background) 0 0 10px; @@ -125,10 +127,10 @@ ul.deflist-flowchart { .arrow-cycle, .arrow-multiple { &::after { - translate: 10px 0; + translate: calc(0.5 * var(--arrow-multiple-gap)) 0; } &::before { - translate: -10px 0; + translate: calc(-0.5 * var(--arrow-multiple-gap)) 0; } } @@ -140,7 +142,7 @@ ul.deflist-flowchart { } .arrow-cycle::before { - translate: -10px var(--actual-arrow-length); + translate: calc(-0.5 * var(--arrow-multiple-gap)) var(--actual-arrow-length); } .arrow-aside { @@ -168,13 +170,46 @@ ul.deflist-flowchart { } } + .arrow-combine, .arrow-combine-left, .arrow-combine-right { + &.arrow-down.arrow-tail, &.arrow-up.arrow-head { + --arrow-combine-gradient-angle: 0deg; + padding-bottom: calc(0.5 * var(--arrow-thickness)); + margin-bottom: calc(-0.5 * var(--arrow-thickness)); + } + &.arrow-up.arrow-tail, &.arrow-down.arrow-head { + --arrow-combine-gradient-angle: 180deg; + padding-top: calc(0.5 * var(--arrow-thickness)); + margin-top: calc(-0.5 * var(--arrow-thickness)); + } + background-image: + linear-gradient( + var(--arrow-combine-gradient-angle), + var(--arrow-color) var(--arrow-thickness), + transparent var(--arrow-thickness) + ); + background-repeat: no-repeat; - .arrow-combine::before { - background: var(--arrow-color); - height: var(--arrow-thickness); - display: block; - content: ""; - margin: calc(-0.5 * var(--arrow-thickness)) 20px; + width: calc(100% + 2 * var(--flowchart-column-gap)); + margin-left: calc(-1 * var(--flowchart-column-gap)); + margin-right: calc(-1 * var(--flowchart-column-gap)); + + &.arrow-combine-left, &.arrow-combine-right { + background-size: 50%; + width: calc(100% + var(--flowchart-column-gap)); + + &.arrow-multiple { + background-size: calc(50% + 0.5 * var(--arrow-multiple-gap)); + } + } + + &.arrow-combine-right { + background-position-x: 100%; + margin-left: 0; + } + + &.arrow-combine-left { + margin-right: 0; + } } dl { diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 67198cebc..fa00393b0 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -119,7 +119,7 @@ Network-First Workflow - :class:`ChemicalSystem` The complete system of chemical components required to simulate a given transformation target. - .. rst-class:: arrow-down arrow-multiple arrow-tail + .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right - - - .. container:: flowchart-sidebyside @@ -128,13 +128,13 @@ Network-First Workflow Small molecule components describe the ligands that will be mutated. - .. rst-class:: arrow-down arrow-multiple arrow-tail + .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right - - - :class:`LigandAtomMapper` Generates atom maps between one molecule and another. - .. rst-class:: arrow-down arrow-tail + .. rst-class:: arrow-down arrow-tail arrow-combine - - - @@ -143,19 +143,16 @@ Network-First Workflow - :any:`Atom Map Scorers` Objective function for optimization of a ligand network. - .. rst-class:: arrow-down arrow-tail + .. rst-class:: arrow-down arrow-tail arrow-combine-left - - .. rst-class:: arrow-combine - - - .. rst-class:: arrow-down arrow-head - - :class:`LigandNetwork` A network of ligand transformations. - .. rst-class:: arrow-down arrow-tail + .. rst-class:: arrow-down arrow-tail arrow-combine - - @@ -166,13 +163,9 @@ Network-First Workflow - :class:`Protocol` Simulation procedure for an alchemic mutation. - .. rst-class:: arrow-down arrow-tail + .. rst-class:: arrow-down arrow-tail arrow-combine-left - - - .. rst-class:: arrow-combine - - - .. rst-class:: arrow-down arrow-head - @@ -198,7 +191,7 @@ Transformation-First Workflow - :class:`Protocol` Simulation procedure for an alchemic mutation. - .. rst-class:: arrow-down arrow-tail + .. rst-class:: arrow-down arrow-tail arrow-combine-right - - - Chemical component definition @@ -233,25 +226,22 @@ Transformation-First Workflow - :class:`LigandAtomMapping` Corresponds atoms in one small molecule to those in another. - .. rst-class:: arrow-down arrow-tail + .. rst-class:: arrow-down arrow-tail arrow-combine - - - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` All components are included in the ChemicalSystem - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-multiple - :any:`Assembling into ChemicalSystems` - :class:`ChemicalSystem` The complete system of chemical components required to simulate a given transformation target. - .. rst-class:: arrow-down arrow-tail + .. rst-class:: arrow-down arrow-tail arrow-combine-left - - .. rst-class:: arrow-combine - - - .. rst-class:: arrow-down arrow-head - From 08721ca6be0259a1436cbc606d5fd0f31a173c2e Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 16:51:22 +1000 Subject: [PATCH 09/28] Fix flowchart layout --- docs/_sass/deflist-flowchart.scss | 100 +++++++++++--- docs/cookbook/index.rst | 204 +++++++++++----------------- docs/cookbook/loading_molecules.rst | 4 +- 3 files changed, 160 insertions(+), 148 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 26c430d60..bbacc84bf 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -5,7 +5,9 @@ --arrow-color: var(--pst-color-text-muted); --deflist-def-bg-color: var(--pst-color-surface); --arrow-multiple-gap: 20px; - --flowchart-column-gap: 16px; + --flowchart-column-gap: 15px; + --flowchart-unit-width: 45px; + --flowchart-top-label-space: 1.5rem; } .arrow.thick { --arrow-thickness: 6px; @@ -189,13 +191,14 @@ ul.deflist-flowchart { ); background-repeat: no-repeat; - width: calc(100% + 2 * var(--flowchart-column-gap)); - margin-left: calc(-1 * var(--flowchart-column-gap)); - margin-right: calc(-1 * var(--flowchart-column-gap)); + &:not(.arrow-combine-left):not(.arrow-combine-right) { + width: calc(100% + 2 * var(--flowchart-column-gap)); + margin-left: calc(-1 * var(--flowchart-column-gap)); + margin-right: calc(-1 * var(--flowchart-column-gap)); + } &.arrow-combine-left, &.arrow-combine-right { background-size: 50%; - width: calc(100% + var(--flowchart-column-gap)); &.arrow-multiple { background-size: calc(50% + 0.5 * var(--arrow-multiple-gap)); @@ -204,11 +207,15 @@ ul.deflist-flowchart { &.arrow-combine-right { background-position-x: 100%; - margin-left: 0; } + } - &.arrow-combine-left { - margin-right: 0; + > ul > li { + &.arrow-down, + &.arrow-up, + &.arrow-cycle { + width: calc(100% - var(--flowchart-top-label-space)); + margin-left: 0; } } @@ -216,22 +223,26 @@ ul.deflist-flowchart { display: flex; flex-direction: row-reverse; margin: 0; + padding: 0 0.5em; } dt { display: inline-block; writing-mode: vertical-rl; margin-top: .25rem; flex-grow: 0; + width: var(--flowchart-top-label-space) } dd { text-align: center; position: relative; border: 1px solid var(--pst-color-border); border-radius: .25rem; - padding: 0.5em; margin: 0; display: inline-block; flex-grow: 1; + container-type: inline-size; + container-name: flowchart; + overflow-x: scroll; } dd dl { @@ -241,36 +252,89 @@ ul.deflist-flowchart { 0 1px 18px 0 rgba(0,0,0,0.12), 0 3px 5px -1px rgba(0,0,0,0.4); display: block; - margin: 0.5em 0; + margin: 0.5em auto; + padding: 0.25em 0.75em; + max-width: fit-content; //calc(10 * var(--flowchart-unit-width) + 9 * var(--flowchart-column-gap)); + min-width: calc(2 * var(--flowchart-unit-width) + var(--flowchart-column-gap)); } dd dt { writing-mode: horizontal-tb; display: block; margin-top: 0; + width: unset; } dd dd { border: none; display: block; + container-type: unset; + overflow-x: unset; + } + + dd > ul { + min-width: fit-content; + padding: 0.5rem; + } + + dd dd > ul { + min-width: unset; + padding: 0; } dl a { font-weight: bold; } - .flowchart-sidebyside, div.flowchart-sidebyside > ul:only-child { + div.flowchart-sidebyside > ul:only-child { display: flex; flex-direction: row; flex-wrap: nowrap; - > .flowchart-narrow { - flex: 0; - min-width: 200px; - } - > * { - flex: 1; - } } .flowchart-spacer { height: 99999% } + + .width-2 { + width: calc(2 * var(--flowchart-unit-width) + var(--flowchart-column-gap)); + } + .width-3 { + width: calc(3 * var(--flowchart-unit-width) + 2 * var(--flowchart-column-gap)); + } + .width-4 { + width: calc(4 * var(--flowchart-unit-width) + 3 * var(--flowchart-column-gap)); + } + .width-5 { + width: calc(5 * var(--flowchart-unit-width) + 4 * var(--flowchart-column-gap)); + } + .width-6 { + width: calc(6 * var(--flowchart-unit-width) + 5 * var(--flowchart-column-gap)); + } + .width-7 { + width: calc(7 * var(--flowchart-unit-width) + 6 * var(--flowchart-column-gap)); + } + .width-8 { + width: calc(8 * var(--flowchart-unit-width) + 7 * var(--flowchart-column-gap)); + } + .width-9 { + width: calc(9 * var(--flowchart-unit-width) + 8 * var(--flowchart-column-gap)); + } + .width-10 { + width: calc(10 * var(--flowchart-unit-width) + 9 * var(--flowchart-column-gap)); + } + li { + &.width-2, + &.width-3, + &.width-4, + &.width-5, + &.width-6, + &.width-7, + &.width-8, + &.width-9, + &.width-10, + &.width-full { + > dl { + max-width: unset; + } + } + } } \ No newline at end of file diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index fa00393b0..972591ca2 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -6,153 +6,71 @@ This will include various how-to guides. .. module:: openfe :noindex: -Basic Workflow --------------- - +Network-First Workflow +----------------------------- .. container:: deflist-flowchart * Setup - - .. container:: flowchart-sidebyside + - .. container:: width-7 - - + - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + + - .. container:: flowchart-sidebyside - .. rst-class:: flowchart-narrow - - - .. rst-class:: flowchart-spacer - - - - :class:`Protocol` - Simulation procedure for an alchemic mutation. + .. rst-class:: arrow-down arrow-multiple + - :any:`Loading proteins`, :any:`Defining solvents` - .. rst-class:: arrow-down - - + .. rst-class:: width-3 + - :class:`SolventComponent`, :class:`ProteinComponent` + Other chemical components needed to simulate the ligand. - - - Chemical component definition - SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right + - - - .. container:: flowchart-sidebyside + - - .. container:: flowchart-sidebyside - - - .. rst-class:: flowchart-narrow - - - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-multiple - :any:`Loading small molecules` + .. rst-class:: width-4 - :class:`SmallMoleculeComponent` - Small molecule components describe the ligands that will be mutated. - - .. rst-class:: arrow-down arrow-downright arrow-multiple - - + The ligands that will be mutated. - - - .. container:: flowchart-sidebyside - - - - - - .. rst-class:: arrow-down - - :any:`Defining solvents` - - :class:`SolventComponent` - Small molecule components describe the ligands that will be mutated. - - .. rst-class:: arrow-down - - - - - - - - .. rst-class:: arrow-down - - :any:`Loading proteins` - - - :class:`ProteinComponent` - Small molecule components describe the ligands that will be mutated. - - .. rst-class:: arrow-down - - - - - :class:`ChemicalSystem` - The complete system of chemical components required to simulate a given transformation target. - - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right - - - :any:`Alchemical Network Planning` - Classes to plan a simulation campaign. - - .. rst-class:: arrow-down - - - - - :class:`AlchemicalNetwork` - A complete description of a simulation campaign, consisting of a collection of :class:`Transformation` objects and a :class:`ChemicalSystem` for each ligand the transformations connect. - - .. rst-class:: arrow-down - * - - * Run - - term - def - - .. rst-class:: arrow-down - * - - * Gather - - term - def - -Network-First Workflow ------------------------------ - -.. container:: deflist-flowchart - - * Setup - - .. container:: flowchart-sidebyside - - - - .. rst-class:: flowchart-narrow - - - - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` - All components are included in the ChemicalSystem - - .. rst-class:: arrow-down - - :any:`Assembling into ChemicalSystems` - - - :class:`ChemicalSystem` - The complete system of chemical components required to simulate a given transformation target. - - .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right - - - - - - .. container:: flowchart-sidebyside - - - - :class:`SmallMoleculeComponent` - Small molecule components describe the ligands that will be mutated. - + - - - .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right - - + - :class:`LigandAtomMapper` + Generates atom maps between one molecule and another. - - - :class:`LigandAtomMapper` - Generates atom maps between one molecule and another. + .. rst-class:: arrow-down arrow-tail arrow-combine + - - .. rst-class:: arrow-down arrow-tail arrow-combine - - + - - + .. rst-class:: flowchart-spacer + - - - - - .. rst-class:: flowchart-spacer - - - - :any:`Atom Map Scorers` - Objective function for optimization of a ligand network. + - :any:`Atom Map Scorers` + Objective function for optimization of a ligand network. - .. rst-class:: arrow-down arrow-tail arrow-combine-left - - + .. rst-class:: arrow-down arrow-tail arrow-combine-left + - .. rst-class:: arrow-down arrow-head - - :class:`LigandNetwork` - A network of ligand transformations. + A network of ligand transformations. - .. rst-class:: arrow-down arrow-tail arrow-combine + .. rst-class:: arrow-down arrow-tail arrow-combine - - @@ -163,7 +81,7 @@ Network-First Workflow - :class:`Protocol` Simulation procedure for an alchemic mutation. - .. rst-class:: arrow-down arrow-tail arrow-combine-left + .. rst-class:: arrow-down arrow-tail arrow-combine-left - .. rst-class:: arrow-down arrow-head @@ -172,6 +90,20 @@ Network-First Workflow - :class:`AlchemicalNetwork` A complete simulation campaign. + .. rst-class:: arrow-down + * + + * Run + - term + def + + .. rst-class:: arrow-down + * + + * Gather + - term + def + Transformation-First Workflow ----------------------------- @@ -181,9 +113,6 @@ Transformation-First Workflow * Setup - .. container:: flowchart-sidebyside - - - - .. rst-class:: flowchart-narrow - - .. rst-class:: flowchart-spacer - @@ -197,15 +126,16 @@ Transformation-First Workflow - - Chemical component definition SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. - .. rst-class:: arrow-down + .. rst-class:: arrow-down arrow-tail - :any:`Loading Molecules` - - Component - A component of a chemical system. - - .. container:: flowchart-sidebyside - - - :class:`SmallMoleculeComponent` + - - + .. rst-class:: arrow-down arrow-head arrow-combine-right + - + + - :class:`SmallMoleculeComponent` Small molecule components describe the ligands that will be mutated. - .. container:: flowchart-sidebyside @@ -215,6 +145,7 @@ Transformation-First Workflow - - :class:`LigandNetwork` + A network of ligand transformations. .. rst-class:: arrow-down arrow-multiple - @@ -229,17 +160,20 @@ Transformation-First Workflow .. rst-class:: arrow-down arrow-tail arrow-combine - - - + - - + .. rst-class:: arrow-down arrow-head arrow-combine-left + - + - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` All components are included in the ChemicalSystem - .. rst-class:: arrow-down arrow-multiple + .. rst-class:: arrow-down arrow-multiple - :any:`Assembling into ChemicalSystems` - :class:`ChemicalSystem` The complete system of chemical components required to simulate a given transformation target. - .. rst-class:: arrow-down arrow-tail arrow-combine-left + .. rst-class:: arrow-down arrow-tail arrow-combine-left - .. rst-class:: arrow-down arrow-head @@ -248,13 +182,27 @@ Transformation-First Workflow - :class:`Transformation` A single transformation - .. rst-class:: arrow-down + .. rst-class:: arrow-down - - :class:`AlchemicalNetwork` A complete description of a simulation campaign, consisting of a collection of :class:`Transformation` objects and a :class:`ChemicalSystem` for each ligand the transformations connect. + .. rst-class:: arrow-down + * + + * Run + - term + def + + .. rst-class:: arrow-down + * + + * Gather + - term + def + .. toctree:: diff --git a/docs/cookbook/loading_molecules.rst b/docs/cookbook/loading_molecules.rst index 698763437..94d12426f 100644 --- a/docs/cookbook/loading_molecules.rst +++ b/docs/cookbook/loading_molecules.rst @@ -1,7 +1,7 @@ .. _Loading Molecules: -Loading your data into ChemicalSystems -====================================== +Loading your data into Components +================================= One of the first tasks you'll likely want to do is loading your various input files. In ``openfe`` the entire contents of a simulation volume, for example the ligand, protein and water is referred to From 6f4fda78e9905723aa2bed63b6d3d9938cc3be9e Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 17:20:33 +1000 Subject: [PATCH 10/28] Fix overflow and branching arrows --- docs/_sass/deflist-flowchart.scss | 8 +++----- docs/cookbook/index.rst | 2 +- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index bbacc84bf..093fa29df 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -191,14 +191,12 @@ ul.deflist-flowchart { ); background-repeat: no-repeat; - &:not(.arrow-combine-left):not(.arrow-combine-right) { - width: calc(100% + 2 * var(--flowchart-column-gap)); - margin-left: calc(-1 * var(--flowchart-column-gap)); - margin-right: calc(-1 * var(--flowchart-column-gap)); - } + margin-left: calc(-0.5 * var(--flowchart-column-gap)); + width: calc(100% + 2 * var(--flowchart-column-gap)); &.arrow-combine-left, &.arrow-combine-right { background-size: 50%; + width: calc(100% + var(--flowchart-column-gap)); &.arrow-multiple { background-size: calc(50% + 0.5 * var(--arrow-multiple-gap)); diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 972591ca2..cb01c774d 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -75,7 +75,7 @@ Network-First Workflow - - - .. rst-class:: flowchart-spacer + .. rst-class:: flowchart-spacer - - :class:`Protocol` From a587260babdebeff90ca7fe3dcd2ae31a822dc08 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 17:27:22 +1000 Subject: [PATCH 11/28] Fix arrow alignment --- docs/_sass/deflist-flowchart.scss | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 093fa29df..cd3d4b28f 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -191,12 +191,13 @@ ul.deflist-flowchart { ); background-repeat: no-repeat; - margin-left: calc(-0.5 * var(--flowchart-column-gap)); width: calc(100% + 2 * var(--flowchart-column-gap)); + margin-left: calc(-1 * var(--flowchart-column-gap)); &.arrow-combine-left, &.arrow-combine-right { background-size: 50%; width: calc(100% + var(--flowchart-column-gap)); + margin-left: calc(-0.5 * var(--flowchart-column-gap)); &.arrow-multiple { background-size: calc(50% + 0.5 * var(--arrow-multiple-gap)); From f43b13b06912ace292f56ae3bb87167c7eb41e5e Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 18:58:41 +1000 Subject: [PATCH 12/28] Pin Sphinx 7.1 --- docs/environment.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/environment.yaml b/docs/environment.yaml index effa35f61..58b693a71 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -12,7 +12,7 @@ dependencies: - plugcli - pydata-sphinx-theme - python=3.9 -- sphinx +- sphinx=7.1 - sphinx-click - tqdm - libsass From fe234f794c4627f516d879566259b39ef61f48a3 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 19:08:48 +1000 Subject: [PATCH 13/28] Pin Sphinx <7 --- docs/environment.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/environment.yaml b/docs/environment.yaml index 58b693a71..dad640d34 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -12,7 +12,7 @@ dependencies: - plugcli - pydata-sphinx-theme - python=3.9 -- sphinx=7.1 +- sphinx<7 - sphinx-click - tqdm - libsass From 0a2fb8b398fe0964f198250a6cd673edfde42cce Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Thu, 17 Aug 2023 19:28:14 +1000 Subject: [PATCH 14/28] Add sphinx pin to pip --- docs/environment.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/environment.yaml b/docs/environment.yaml index dad640d34..476e10c00 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -19,4 +19,5 @@ dependencies: - pip: - sphinx-design - sphinx-toolbox + - sphinx<7 - git+https://github.com/OpenFreeEnergy/gufe@main From 689b9fc8a0d2f4eaccb0c1d9d1e531bf15d8089e Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 21 Aug 2023 16:07:53 +1000 Subject: [PATCH 15/28] Improve arrow label readability --- docs/_sass/deflist-flowchart.scss | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index cd3d4b28f..f64916653 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -74,7 +74,6 @@ ul.deflist-flowchart { margin: 0.75em auto; position: relative; z-index: 1; - text-shadow: var(--pst-color-background) 0 0 10px; padding: 0; &::before, &::after { @@ -115,6 +114,12 @@ ul.deflist-flowchart { var(--arrow-tail-gradient); } } + + > p { + background: var(--pst-color-background); + margin: calc(var(--arrow-length) / 2) 0 !important; + line-height: 1.5; + } } .arrow-down, From 6cd4ee1e70aa3a4ac3bf21cfc23705bfbfc8bb19 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 21 Aug 2023 20:09:03 +1000 Subject: [PATCH 16/28] Tighten up flowchart spacing --- docs/_sass/deflist-flowchart.scss | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index f64916653..2e0515f39 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -5,9 +5,10 @@ --arrow-color: var(--pst-color-text-muted); --deflist-def-bg-color: var(--pst-color-surface); --arrow-multiple-gap: 20px; - --flowchart-column-gap: 15px; --flowchart-unit-width: 45px; - --flowchart-top-label-space: 1.5rem; + --flowchart-spacing: 0.5rem; + --flowchart-column-gap: calc(1.5 * var(--flowchart-spacing)); + --flowchart-top-label-space: calc(3 * var(--flowchart-spacing)); } .arrow.thick { --arrow-thickness: 6px; @@ -71,7 +72,7 @@ ul.deflist-flowchart { min-height: var(--arrow-length); height: 100%; width: 100%; - margin: 0.75em auto; + margin: calc(2 * var(--flowchart-spacing)) auto; position: relative; z-index: 1; padding: 0; @@ -227,7 +228,7 @@ ul.deflist-flowchart { display: flex; flex-direction: row-reverse; margin: 0; - padding: 0 0.5em; + padding: 0 var(--flowchart-spacing); } dt { display: inline-block; @@ -256,9 +257,9 @@ ul.deflist-flowchart { 0 1px 18px 0 rgba(0,0,0,0.12), 0 3px 5px -1px rgba(0,0,0,0.4); display: block; - margin: 0.5em auto; - padding: 0.25em 0.75em; - max-width: fit-content; //calc(10 * var(--flowchart-unit-width) + 9 * var(--flowchart-column-gap)); + margin: 0 auto; + padding: calc(var(--flowchart-spacing) / 2); + max-width: calc(100cqw - 2 * var(--flowchart-spacing)); min-width: calc(2 * var(--flowchart-unit-width) + var(--flowchart-column-gap)); } dd dt { @@ -272,16 +273,19 @@ ul.deflist-flowchart { display: block; container-type: unset; overflow-x: unset; + padding: calc(var(--flowchart-spacing) / 2); } dd > ul { - min-width: fit-content; - padding: 0.5rem; + width: fit-content; + padding: var(--flowchart-spacing); + margin: 0 auto; } dd dd > ul { min-width: unset; padding: 0; + margin: 0; } dl a { @@ -292,10 +296,12 @@ ul.deflist-flowchart { display: flex; flex-direction: row; flex-wrap: nowrap; + justify-content: center; } .flowchart-spacer { - height: 99999% + height: 99999%; + min-height: calc(2 * var(--flowchart-spacing)); } .width-2 { From 556e51a4c05faadb0ab9a2b28b7f7c0672679668 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 21 Aug 2023 20:40:04 +1000 Subject: [PATCH 17/28] Make links in flowcharts more consistent --- docs/_sass/deflist-flowchart.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 2e0515f39..98b4893e1 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -288,7 +288,7 @@ ul.deflist-flowchart { margin: 0; } - dl a { + dl a, a { font-weight: bold; } From cbc4caac2f58bc131e7c4e5c0b219d1b8cd758c4 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 21 Aug 2023 20:40:44 +1000 Subject: [PATCH 18/28] Add executors anchor to reference --- docs/reference/api/defining_and_executing_simulations.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/api/defining_and_executing_simulations.rst b/docs/reference/api/defining_and_executing_simulations.rst index efa15ff16..51cc3df34 100644 --- a/docs/reference/api/defining_and_executing_simulations.rst +++ b/docs/reference/api/defining_and_executing_simulations.rst @@ -1,6 +1,8 @@ Defining and Executing Simulations ================================== +.. _executors: + Executing Simulations --------------------- From 4a2fabf73169a47727c34f87eb50b8179e1d852c Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 21 Aug 2023 20:41:00 +1000 Subject: [PATCH 19/28] Finish up initial flowchart --- docs/cookbook/index.rst | 76 ++++++++++++++++++++++++++--------------- 1 file changed, 49 insertions(+), 27 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index cb01c774d..2e32d5e33 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -1,13 +1,19 @@ Cookbook ======== -This will include various how-to guides. +This section describes common tasks involving the OpenFE Python API. + +The :any:`OpenFE CLI` provides a simple way to perform the most common procedures for free energy calculations, but does not provide much flexibility for fine-tuning your approach or combining OpenFE with other tools. The :any:`Python API` allows that flexibility, but using it is more complex. This cookbook breaks down common steps that would be implemented in Python to help navigate that complexity. + +.. note:: This section is a work-in-progress. .. module:: openfe :noindex: -Network-First Workflow ------------------------------ +The Basic Workflow +------------------ + +The typical way to use the Python API is to load a number of molecules you want to calculate free energies of, construct a :class:`LigandNetwork` connecting them in an efficient way, and then combine that with information for how each ligand should be simulated to construct an :class:`AlchemicalNetwork`, which specifies the entire simulation campaign. This provides a lot of flexibility in how molecules are specified, mapped, connected, and simulated, without exposing a great deal of complexity. OpenFE recommends this workflow for most users. .. container:: deflist-flowchart @@ -25,7 +31,7 @@ Network-First Workflow - :any:`Loading proteins`, :any:`Defining solvents` .. rst-class:: width-3 - - :class:`SolventComponent`, :class:`ProteinComponent` + - :class:`SolventComponent` and :class:`ProteinComponent` Other chemical components needed to simulate the ligand. .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right @@ -91,23 +97,25 @@ Network-First Workflow A complete simulation campaign. .. rst-class:: arrow-down - * + * :any:`dumping_transformations` * Run - - term - def + - :any:`openfe quickrun ` + OpenFE recommends using the ``openfe quickrun`` CLI command to execute a transformation. .. rst-class:: arrow-down * * Gather - - term - def + - :any:`openfe gather ` + OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation. Transformation-First Workflow ----------------------------- +If you want to implement your own atom mapper or free energy procedure, or you want to do something a bit more bespoke, it's helpful to understand how OpenFE thinks about individual alchemic mutation specifications. A :class:`Transformation` stores all the information needed to run an alchemic mutation from one chemical system to another and is the basic unit of an OpenFE simulation campaign. Indeed, :class:`Transformation` objects describe the edges of the graph in the :class:`AlchemicalNetwork` class. + .. container:: deflist-flowchart * Setup @@ -136,7 +144,7 @@ Transformation-First Workflow - - :class:`SmallMoleculeComponent` - Small molecule components describe the ligands that will be mutated. + The ligands that will be mutated. - .. container:: flowchart-sidebyside @@ -164,47 +172,61 @@ Transformation-First Workflow .. rst-class:: arrow-down arrow-head arrow-combine-left - - - :class:`SmallMoleculeComponent`, :class:`SolventComponent`, :class:`ProteinComponent` - All components are included in the ChemicalSystem + - :class:`SmallMoleculeComponent`, :class:`SolventComponent` and :class:`ProteinComponent` + The components that make up the chemical system. .. rst-class:: arrow-down arrow-multiple - :any:`Assembling into ChemicalSystems` - :class:`ChemicalSystem` - The complete system of chemical components required to simulate a given transformation target. + Each of the chemical systems, composed of components, that the :class:`Transformation` mutates between. - .. rst-class:: arrow-down arrow-tail arrow-combine-left + .. rst-class:: arrow-down arrow-tail arrow-combine-left arrow-multiple - .. rst-class:: arrow-down arrow-head - - :class:`Transformation` - A single transformation + A single alchemic mutation from one chemical system to another. + + .. rst-class:: arrow-down + * + + * Run + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. .. rst-class:: arrow-down - + - :class:`ProtocolDAG` + A directed acyclic graph describing how to compute a :class:`Transformation`. - - :class:`AlchemicalNetwork` - A complete description of a simulation campaign, consisting of a collection of :class:`Transformation` objects and a :class:`ChemicalSystem` for each ligand the transformations connect. + - .. container:: flowchart-sidebyside - .. rst-class:: arrow-down - * + - + - + .. rst-class:: arrow-down arrow-multiple + - - * Run - - term - def + - :class:`ProtocolUnit` + A single unit of computation within a :class:`ProtocolDAG` - .. rst-class:: arrow-down - * + .. rst-class:: arrow-down arrow-multiple + - - * Gather - - term - def + - + - + .. rst-class:: arrow-down + - :any:`executors` + + - :class:`ProtocolDAGResult` + A completed transformation. .. toctree:: + :hidden: loading_molecules creating_atom_mappings From d3f35417828937deb0034d4003619bcb561e2b34 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 21 Aug 2023 20:58:43 +1000 Subject: [PATCH 20/28] Synchronise RTD and docs environments --- docs/environment.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/environment.yaml b/docs/environment.yaml index 476e10c00..7fcefaf27 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -21,3 +21,10 @@ dependencies: - sphinx-toolbox - sphinx<7 - git+https://github.com/OpenFreeEnergy/gufe@main + +# These are added automatically by RTD, so we include them here +# for a consistent environment. +- mock +- pillow +- sphinx +- sphinx_rtd_theme From 59ae11d6ace1983d2196d5482e2e75792e7cca14 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Wed, 23 Aug 2023 09:50:59 +1000 Subject: [PATCH 21/28] Chrome compatibility --- docs/_sass/deflist-flowchart.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 98b4893e1..b4395ef7d 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -247,7 +247,7 @@ ul.deflist-flowchart { flex-grow: 1; container-type: inline-size; container-name: flowchart; - overflow-x: scroll; + overflow-x: auto; } dd dl { From d33f929f25a0fcf4cb58cee778b0a6157a6fbc2f Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Wed, 23 Aug 2023 15:35:42 +1000 Subject: [PATCH 22/28] Support multiple combining arrows from single node --- docs/_sass/deflist-flowchart.scss | 52 +++++++++++++++++++++++++++---- docs/cookbook/index.rst | 2 +- 2 files changed, 47 insertions(+), 7 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index b4395ef7d..67ad7d9fb 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -2,9 +2,11 @@ --arrow-thickness: 4px; --arrow-head-size: 7px; --arrow-length: 2em; - --arrow-color: var(--pst-color-text-muted); - --deflist-def-bg-color: var(--pst-color-surface); --arrow-multiple-gap: 20px; + --arrow-color: var(--pst-color-text-muted); + --flowchart-def-bg-color: var(--pst-color-surface); + --flowchart-bg-color: var(--pst-color-background); + --flowchart-def-border-color: var(--pst-color-border); --flowchart-unit-width: 45px; --flowchart-spacing: 0.5rem; --flowchart-column-gap: calc(1.5 * var(--flowchart-spacing)); @@ -117,9 +119,10 @@ ul.deflist-flowchart { } > p { - background: var(--pst-color-background); + background: var(--flowchart-bg-color); margin: calc(var(--arrow-length) / 2) 0 !important; line-height: 1.5; + z-index: 10; } } @@ -147,10 +150,13 @@ ul.deflist-flowchart { .arrow-cycle::before { transform: rotate(-135deg); + translate: 0 calc(var(--actual-arrow-length) + 2 * var(--flowchart-spacing) + var(--arrow-head-size) / 2); } .arrow-cycle::before { - translate: calc(-0.5 * var(--arrow-multiple-gap)) var(--actual-arrow-length); + translate: + calc(-0.5 * var(--arrow-multiple-gap)) + calc(var(--actual-arrow-length) + 2 * var(--flowchart-spacing) + var(--arrow-head-size) / 2); } .arrow-aside { @@ -160,6 +166,40 @@ ul.deflist-flowchart { } } + .arrow-multiple-combine { + &::before { + content: ""; + width: var(--arrow-multiple-gap); + border: var(--arrow-thickness) solid var(--arrow-color); + height: calc(var(--arrow-length) / 2); + background: var(--flowchart-bg-color); + transform: none; + left: auto; + z-index: 2; + } + + &.arrow-down { + &::before { + border-top: 1px solid var(--flowchart-bg-color); + } + > p { + margin-top: calc(1.5 * var(--arrow-length)) !important; + margin-bottom: calc(1 * var(--arrow-length)) !important; + } + } + + &.arrow-up { + &::before { + border-bottom: 1px solid var(--flowchart-bg-color); + top: auto; + bottom: -1px; + } + > p { + margin-bottom: var(--arrow-length) !important; + } + } + } + .arrow-tail { &.arrow-down { margin-bottom: 0; @@ -240,7 +280,7 @@ ul.deflist-flowchart { dd { text-align: center; position: relative; - border: 1px solid var(--pst-color-border); + border: 1px solid var(--flowchart-def-border-color); border-radius: .25rem; margin: 0; display: inline-block; @@ -251,7 +291,7 @@ ul.deflist-flowchart { } dd dl { - background-color: var(--deflist-def-bg-color); + background-color: var(--flowchart-def-bg-color); border-radius: 4px; box-shadow: 0 6px 10px 0 rgba(0,0,0,0.14), 0 1px 18px 0 rgba(0,0,0,0.12), diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 2e32d5e33..b9254985d 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -175,7 +175,7 @@ If you want to implement your own atom mapper or free energy procedure, or you w - :class:`SmallMoleculeComponent`, :class:`SolventComponent` and :class:`ProteinComponent` The components that make up the chemical system. - .. rst-class:: arrow-down arrow-multiple + .. rst-class:: arrow-down arrow-multiple-combine - :any:`Assembling into ChemicalSystems` - :class:`ChemicalSystem` From c3eb0b47c129a4c472e81f60559254b095344577 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Wed, 23 Aug 2023 15:38:10 +1000 Subject: [PATCH 23/28] Add ProtocolUnitResult to flowchart --- docs/cookbook/index.rst | 46 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index b9254985d..c0746d580 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -213,9 +213,55 @@ If you want to implement your own atom mapper or free energy procedure, or you w - :class:`ProtocolUnit` A single unit of computation within a :class:`ProtocolDAG` + .. rst-class:: arrow-down + - + + - :class:`ProtocolUnitResult` + The result of a completed :class:`ProtocolUnit` + + .. rst-class:: arrow-down arrow-multiple-combine + - + + - + - + .. rst-class:: arrow-down + - :any:`executors` + + - :class:`ProtocolDAGResult` + A completed transformation. + + .. rst-class:: arrow-down + * + + * Gather + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. + + .. rst-class:: arrow-down + - + + - :class:`ProtocolDAG` + A directed acyclic graph describing how to compute a :class:`Transformation`. + + - .. container:: flowchart-sidebyside + + - + - .. rst-class:: arrow-down arrow-multiple - + - :class:`ProtocolUnit` + A single unit of computation within a :class:`ProtocolDAG` + + .. rst-class:: arrow-down + - + + - :class:`ProtocolUnitResult` + The result of a completed :class:`ProtocolUnit` + + .. rst-class:: arrow-down arrow-multiple-combine + - + - - .. rst-class:: arrow-down From 4fecd488a8d7d45117dd295789c2cdc47cd432df Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Wed, 23 Aug 2023 15:50:48 +1000 Subject: [PATCH 24/28] Enlarge top-level flowchart headings (Run, Setup, Gather) --- docs/_sass/deflist-flowchart.scss | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index 67ad7d9fb..e701da6c8 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -10,7 +10,7 @@ --flowchart-unit-width: 45px; --flowchart-spacing: 0.5rem; --flowchart-column-gap: calc(1.5 * var(--flowchart-spacing)); - --flowchart-top-label-space: calc(3 * var(--flowchart-spacing)); + --flowchart-top-label-space: 26px; } .arrow.thick { --arrow-thickness: 6px; @@ -275,7 +275,8 @@ ul.deflist-flowchart { writing-mode: vertical-rl; margin-top: .25rem; flex-grow: 0; - width: var(--flowchart-top-label-space) + width: var(--flowchart-top-label-space); + font-size: 1.1em; } dd { text-align: center; @@ -307,6 +308,7 @@ ul.deflist-flowchart { display: block; margin-top: 0; width: unset; + font-size: unset; } dd dd { border: none; From 2e1fa67974d10fbf3850bf3ec6894327fb5e1cf9 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Wed, 23 Aug 2023 15:51:14 +1000 Subject: [PATCH 25/28] Add 'Gather' section to under-the-hood flowchart --- docs/cookbook/index.rst | 51 +++++++++++++---------------------------- 1 file changed, 16 insertions(+), 35 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index c0746d580..13865942e 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -146,21 +146,8 @@ If you want to implement your own atom mapper or free energy procedure, or you w - :class:`SmallMoleculeComponent` The ligands that will be mutated. - - .. container:: flowchart-sidebyside - - - - - .. rst-class:: arrow-down arrow-multiple - - - - - :class:`LigandNetwork` - A network of ligand transformations. - - .. rst-class:: arrow-down arrow-multiple - - - - - - - .. rst-class:: arrow-down - - :any:`Creating Atom Mappings` + .. rst-class:: arrow-down + - :any:`Creating Atom Mappings` - :class:`LigandAtomMapping` Corresponds atoms in one small molecule to those in another. @@ -234,41 +221,35 @@ If you want to implement your own atom mapper or free energy procedure, or you w * * Gather - - :class:`Transformation` - A single alchemic mutation from one chemical system to another. - - .. rst-class:: arrow-down - - - - - :class:`ProtocolDAG` - A directed acyclic graph describing how to compute a :class:`Transformation`. - - .. container:: flowchart-sidebyside - - - - .. rst-class:: arrow-down arrow-multiple - - - - :class:`ProtocolUnit` - A single unit of computation within a :class:`ProtocolDAG` + - :class:`Transformation` + The specification for the alchemic mutation. .. rst-class:: arrow-down - - - :class:`ProtocolUnitResult` - The result of a completed :class:`ProtocolUnit` + - :class:`Protocol` + A completed single run of a transformation. - .. rst-class:: arrow-down arrow-multiple-combine + .. rst-class:: arrow-down arrow-combine-right arrow-tail - - + + - :class:`ProtocolDAGResult` + A completed single run of a transformation. + + .. rst-class:: arrow-down arrow-combine-left arrow-multiple arrow-tail - - .. rst-class:: arrow-down - - :any:`executors` + + .. rst-class:: arrow-down arrow-head + - - :class:`ProtocolDAGResult` - A completed transformation. + A completed transformation with multiple user-defined replicas. .. toctree:: From 04a64d9f29c8809d2280d5f4efad741a56ecb25d Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 28 Aug 2023 19:20:36 +1000 Subject: [PATCH 26/28] Move transformation-first workflow to its own page --- docs/cookbook/index.rst | 146 +------------------------------ docs/cookbook/under_the_hood.rst | 145 ++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+), 143 deletions(-) create mode 100644 docs/cookbook/under_the_hood.rst diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 13865942e..187fcfd1c 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -110,153 +110,13 @@ The typical way to use the Python API is to load a number of molecules you want - :any:`openfe gather ` OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation. - -Transformation-First Workflow ------------------------------ - -If you want to implement your own atom mapper or free energy procedure, or you want to do something a bit more bespoke, it's helpful to understand how OpenFE thinks about individual alchemic mutation specifications. A :class:`Transformation` stores all the information needed to run an alchemic mutation from one chemical system to another and is the basic unit of an OpenFE simulation campaign. Indeed, :class:`Transformation` objects describe the edges of the graph in the :class:`AlchemicalNetwork` class. - -.. container:: deflist-flowchart - - * Setup - - .. container:: flowchart-sidebyside - - - - - .. rst-class:: flowchart-spacer - - - - - :class:`Protocol` - Simulation procedure for an alchemic mutation. - - .. rst-class:: arrow-down arrow-tail arrow-combine-right - - - - - - Chemical component definition - SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. - - .. rst-class:: arrow-down arrow-tail - - :any:`Loading Molecules` - - - .. container:: flowchart-sidebyside - - - - - .. rst-class:: arrow-down arrow-head arrow-combine-right - - - - - :class:`SmallMoleculeComponent` - The ligands that will be mutated. - - .. rst-class:: arrow-down - - :any:`Creating Atom Mappings` - - - :class:`LigandAtomMapping` - Corresponds atoms in one small molecule to those in another. - - .. rst-class:: arrow-down arrow-tail arrow-combine - - - - - - - .. rst-class:: arrow-down arrow-head arrow-combine-left - - - - - :class:`SmallMoleculeComponent`, :class:`SolventComponent` and :class:`ProteinComponent` - The components that make up the chemical system. - - .. rst-class:: arrow-down arrow-multiple-combine - - :any:`Assembling into ChemicalSystems` - - - :class:`ChemicalSystem` - Each of the chemical systems, composed of components, that the :class:`Transformation` mutates between. - - .. rst-class:: arrow-down arrow-tail arrow-combine-left arrow-multiple - - - - .. rst-class:: arrow-down arrow-head - - - - - :class:`Transformation` - A single alchemic mutation from one chemical system to another. - - .. rst-class:: arrow-down - * - - * Run - - :class:`Transformation` - A single alchemic mutation from one chemical system to another. - - .. rst-class:: arrow-down - - - - - :class:`ProtocolDAG` - A directed acyclic graph describing how to compute a :class:`Transformation`. - - - .. container:: flowchart-sidebyside - - - - - - .. rst-class:: arrow-down arrow-multiple - - - - - :class:`ProtocolUnit` - A single unit of computation within a :class:`ProtocolDAG` - - .. rst-class:: arrow-down - - - - - :class:`ProtocolUnitResult` - The result of a completed :class:`ProtocolUnit` - - .. rst-class:: arrow-down arrow-multiple-combine - - - - - - - - .. rst-class:: arrow-down - - :any:`executors` - - - :class:`ProtocolDAGResult` - A completed transformation. - - .. rst-class:: arrow-down - * - - * Gather - - .. container:: flowchart-sidebyside - - - - - - :class:`Transformation` - The specification for the alchemic mutation. - - .. rst-class:: arrow-down - - - - - :class:`Protocol` - A completed single run of a transformation. - - .. rst-class:: arrow-down arrow-combine-right arrow-tail - - - - - - - - :class:`ProtocolDAGResult` - A completed single run of a transformation. - - .. rst-class:: arrow-down arrow-combine-left arrow-multiple arrow-tail - - - - .. rst-class:: arrow-down arrow-head - - - - - :class:`ProtocolDAGResult` - A completed transformation with multiple user-defined replicas. - +List of Cookbooks +----------------- .. toctree:: - :hidden: - loading_molecules creating_atom_mappings dumping_transformation + under_the_hood diff --git a/docs/cookbook/under_the_hood.rst b/docs/cookbook/under_the_hood.rst new file mode 100644 index 000000000..ddd821adb --- /dev/null +++ b/docs/cookbook/under_the_hood.rst @@ -0,0 +1,145 @@ +.. _under-the-hood: + +Under the Hood +============== + +.. module:: openfe + :noindex: + +If you want to implement your own atom mapper or free energy procedure, or you want to do something a bit more bespoke, it's helpful to understand how OpenFE thinks about individual alchemic mutation specifications. A :class:`Transformation` stores all the information needed to run an alchemic mutation from one chemical system to another and is the basic unit of an OpenFE simulation campaign. Indeed, :class:`Transformation` objects describe the edges of the graph in the :class:`AlchemicalNetwork` class. + +.. container:: deflist-flowchart + + * Setup + - .. container:: flowchart-sidebyside + + - - + .. rst-class:: flowchart-spacer + - + + - :class:`Protocol` + Simulation procedure for an alchemic mutation. + + .. rst-class:: arrow-down arrow-tail arrow-combine-right + - + + - - Chemical component definition + SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc. + + .. rst-class:: arrow-down arrow-tail + - :any:`Loading Molecules` + + - .. container:: flowchart-sidebyside + + - - + .. rst-class:: arrow-down arrow-head arrow-combine-right + - + + - :class:`SmallMoleculeComponent` + The ligands that will be mutated. + + .. rst-class:: arrow-down + - :any:`Creating Atom Mappings` + + - :class:`LigandAtomMapping` + Corresponds atoms in one small molecule to those in another. + + .. rst-class:: arrow-down arrow-tail arrow-combine + - + + - - + .. rst-class:: arrow-down arrow-head arrow-combine-left + - + + - :class:`SmallMoleculeComponent`, :class:`SolventComponent` and :class:`ProteinComponent` + The components that make up the chemical system. + + .. rst-class:: arrow-down arrow-multiple-combine + - :any:`Assembling into ChemicalSystems` + + - :class:`ChemicalSystem` + Each of the chemical systems, composed of components, that the :class:`Transformation` mutates between. + + .. rst-class:: arrow-down arrow-tail arrow-combine-left arrow-multiple + - + + .. rst-class:: arrow-down arrow-head + - + + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. + + .. rst-class:: arrow-down + * + + * Run + - :class:`Transformation` + A single alchemic mutation from one chemical system to another. + + .. rst-class:: arrow-down + - + + - :class:`ProtocolDAG` + A directed acyclic graph describing how to compute a :class:`Transformation`. + + - .. container:: flowchart-sidebyside + + - + - + .. rst-class:: arrow-down arrow-multiple + - + + - :class:`ProtocolUnit` + A single unit of computation within a :class:`ProtocolDAG` + + .. rst-class:: arrow-down + - + + - :class:`ProtocolUnitResult` + The result of a completed :class:`ProtocolUnit` + + .. rst-class:: arrow-down arrow-multiple-combine + - + + - + - + .. rst-class:: arrow-down + - :any:`executors` + + - :class:`ProtocolDAGResult` + A completed transformation. + + .. rst-class:: arrow-down + * + + * Gather + - .. container:: flowchart-sidebyside + + - + + - :class:`Transformation` + The specification for the alchemic mutation. + + .. rst-class:: arrow-down + - + + - :class:`Protocol` + A completed single run of a transformation. + + .. rst-class:: arrow-down arrow-combine-right arrow-tail + - + + - + + - :class:`ProtocolResult` + A completed single run of a transformation. + + .. rst-class:: arrow-down arrow-combine-left arrow-multiple arrow-tail + - + + .. rst-class:: arrow-down arrow-head + - + + - :class:`ProtocolDAGResult` + A completed transformation with multiple user-defined replicas. + From b136bcbbe77dd5a88b5adb20f0142963f03cdd48 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 28 Aug 2023 20:01:31 +1000 Subject: [PATCH 27/28] Reduce granularity of basic workflow --- docs/cookbook/index.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 187fcfd1c..e62129365 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -49,30 +49,29 @@ The typical way to use the Python API is to load a number of molecules you want The ligands that will be mutated. - .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine-right + .. rst-class:: arrow-down arrow-multiple - - - + .. rst-class:: flowchart-spacer + - - - :class:`LigandAtomMapper` - Generates atom maps between one molecule and another. + - Orion/FEP+ + Atom mappings from another tool. - .. rst-class:: arrow-down arrow-tail arrow-combine + .. rst-class:: arrow-down - - - .. rst-class:: flowchart-spacer - - - :any:`Atom Map Scorers` - Objective function for optimization of a ligand network. + - :class:`dict` or :class:`list` + Hand-write an atom mapping. - .. rst-class:: arrow-down arrow-tail arrow-combine-left + .. rst-class:: arrow-down - - .. rst-class:: arrow-down arrow-head - - - - :class:`LigandNetwork` A network of ligand transformations. From 6b166c21948dfcbc8fd1a530e2f944e586d01fc9 Mon Sep 17 00:00:00 2001 From: Josh Mitchell Date: Mon, 28 Aug 2023 20:38:44 +1000 Subject: [PATCH 28/28] Fix arrow label positioning and arrow sizing with labels --- docs/_sass/deflist-flowchart.scss | 36 ++++++++++++++----------------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/docs/_sass/deflist-flowchart.scss b/docs/_sass/deflist-flowchart.scss index e701da6c8..4c5dadce6 100644 --- a/docs/_sass/deflist-flowchart.scss +++ b/docs/_sass/deflist-flowchart.scss @@ -68,16 +68,18 @@ ul.deflist-flowchart { .arrow-up, .arrow-cycle { + --arrow-head-size-clamped: calc(min(var(--arrow-head-size), var(--arrow-length) / 2)); + display: flex; justify-content: center; align-items: center; + flex-grow: 1; min-height: var(--arrow-length); - height: 100%; width: 100%; margin: calc(2 * var(--flowchart-spacing)) auto; position: relative; z-index: 1; - padding: 0; + padding: calc(var(--arrow-length) / 4) 0; &::before, &::after { --actual-arrow-length: max(var(--arrow-length), 100%); @@ -92,8 +94,8 @@ ul.deflist-flowchart { --arrow-head-gradient: linear-gradient( -45deg, - var(--arrow-color) var(--arrow-head-size), - transparent var(--arrow-head-size) + var(--arrow-color) var(--arrow-head-size-clamped), + transparent var(--arrow-head-size-clamped) ); height: calc(var(--actual-arrow-length)/1.4142); width: auto; @@ -120,20 +122,19 @@ ul.deflist-flowchart { > p { background: var(--flowchart-bg-color); - margin: calc(var(--arrow-length) / 2) 0 !important; line-height: 1.5; z-index: 10; } } - .arrow-down, + .arrow-down:not(.arrow-tail), .arrow-cycle { - padding-bottom: var(--arrow-head-size); + padding-bottom: calc(var(--arrow-head-size-clamped) + var(--arrow-length) / 4); } - .arrow-up, + .arrow-up:not(.arrow-tail), .arrow-cycle { - padding-top: var(--arrow-head-size); + padding-top: calc(var(--arrow-head-size-clamped) + var(--arrow-length) / 4); } .arrow-cycle, .arrow-multiple { @@ -150,19 +151,19 @@ ul.deflist-flowchart { .arrow-cycle::before { transform: rotate(-135deg); - translate: 0 calc(var(--actual-arrow-length) + 2 * var(--flowchart-spacing) + var(--arrow-head-size) / 2); + translate: 0 calc(var(--actual-arrow-length) + 2 * var(--flowchart-spacing) + var(--arrow-head-size-clamped) / 2); } .arrow-cycle::before { translate: calc(-0.5 * var(--arrow-multiple-gap)) - calc(var(--actual-arrow-length) + 2 * var(--flowchart-spacing) + var(--arrow-head-size) / 2); + calc(var(--actual-arrow-length) + 2 * var(--flowchart-spacing) + var(--arrow-head-size-clamped) / 2); } .arrow-aside { - margin-left: calc(8 * var(--arrow-head-size)); + margin-left: calc(8 * var(--arrow-head-size-clamped)); &::after { - left: calc(-4 * var(--arrow-head-size)); + left: calc(-4 * var(--arrow-head-size-clamped)); } } @@ -179,13 +180,11 @@ ul.deflist-flowchart { } &.arrow-down { + padding-top: calc(0.75 * var(--arrow-length) - var(--arrow-head-size-clamped) / 2); + padding-bottom: calc(0.5 * var(--arrow-head-size-clamped) + 0.25 * var(--arrow-length)); &::before { border-top: 1px solid var(--flowchart-bg-color); } - > p { - margin-top: calc(1.5 * var(--arrow-length)) !important; - margin-bottom: calc(1 * var(--arrow-length)) !important; - } } &.arrow-up { @@ -194,9 +193,6 @@ ul.deflist-flowchart { top: auto; bottom: -1px; } - > p { - margin-bottom: var(--arrow-length) !important; - } } }