Description

This PR will establish the analysis functions for the solvation module. Linked to issues #11, #21, and #28.

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] create ion speciation class
• [x] create coordination number class
• [x] create solvation god class
• [x] update documentation
• [x] finalize data structure
• [x] complete implementation
• [x] finalize in-line documentation

Status

• [x] Ready to go

Description

Provide a brief description of the PR's purpose here.

Todos

• [x] add test data
• [x] functionality to interpolate rdfs
• [x] functionality to find minima
• [x] refine minima finding
• [x] solidify unit testing

Status

• [x] Ready to go

Description

Set up basic testing for current implemented functions.

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] get_radial_shell testing
• [x] get_closest_n_mol testing
• [x] slightly rework get_closest_n_mol signature

Status

• [x] Ready to go

Description

Create a convenient tutorial for users to learn solvation_analysis

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] jupyter tutorial for users
• [x] set up jupyter edit requests

Status

• [x] Ready to go

Some of our proposed functionality follows on directly from other functionality and some does not.

This means we need to discuss how to compartmentalise functionality into classes and methods many of which will subclass analysis base.

I thought I would make this issue as an open discussion area for how we want to compartmentalise /hierarchicalize our functionality. I think the best way to proceed is if @orioncohen can lay out how he sees it and then @richardjgowers @IAlibay and any @MDAnalysis/gsoc-mentors can weigh in. We may also need to meet to discuss this. :)

Description

Since nglview is causing issues and I don't want to get bogged down before the release, I wanted to put this in a separate thread.

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] tutorial introduction
• [x] fix nglview issues
• [x] finish tutorial

Questions

• [x] Why is nglview showing too many bonds on molecules?

Status

• [x] Ready to go

Description

Implements basic functionality for solvation selection. Currently implements get_atom_group, get_n_shells, get_closest_n_mol, and get_radial_shell. Addresses issue #5

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] implement basic functionality for solvation selection
• [x] documentation for functions
• [x] unit tests for basic functionality

Questions

• [x] what doc style should be used?

Status

• [x] ready to go

Description

This PR was split off from PR #70 to better separate quality-of-life changes from API changes. See that PR for some history and discussion.

This is intended to be a major PR to handle multi-atom solutes. It relates to issues #47, #66, and #58.

I would like to propose the following outline of new functionality. In this description, I will focus on the outward facing API. I'll use the somewhat trivial case of water as an example.

1. Solution will be renamed to Solute. All references to solute in the current documentation will be renamed to solvated atom or solvated atoms. I think this better captures what the Solute class really is, especially as we expand to multi-atom Solutes.

2. The default initializer for Solute will take only a single atom per residue. It will not support multiple identical atoms on a residue. This will be handled by the more general case. As a result, instantiating a Solute for a single atom remains the same.

water = u.select_atoms(...)
water_O = u.select_atoms(...)
water_O_solute = Solute(water_O, {"water": water})

4. Additional initializers will be added to instantiate a Solute, these will support multi-atom solutes.

The first will allow the user to stitch together multiple solutes to create a new solute.

water_H1 = u.select_atoms(...)
water_H2 = u.select_atoms(...)
solute_O = Solute(water_O, {"water": water})
solute_H1 = Solute(water_H1, {"water": water})
solute_H2 = Solute(water_H2, {"water": water})

multi_atom_solute = Solute.from_solutes([solute_O, solute_H1, solute_H2])  # maybe this should be a dict?

The second will allow users to simply instantiate a solute from an entire residue (or part of a residue). There may be technical challenges here so this behavior is not guaranteed.

multi_atom_solute = Solute.from_residue(water, {"water": water})

5. To support this, the solvation_data dataframe will have two additional columns added, a "residue" column and a "solute_name" column. All analysis classes will be refactored to operate on the "residue" column rather than the "solvated_atom" column. This will make no difference for single-atom solutes but will allow the analysis classes to generalize easily. I'm not completely sure the "solute_name" column is necessary, but it would be convenient to have.

6. When a multi-atom solute is created all of the solvation_data dataframes from each constituent single-atom solute will be merged together. The "residue" column will group together solvated atoms on the same residue such that the analysis classes can operate on the whole solute. The API for accessing the residence classes will be identical.

multi_atom_solute.coordination_number["water"]   # valid property

7. We will retain all of the single atom Solutes as a property of the multi-atom Solute. This would amount to a rough doubling of the memory footprint, but it would make follow up analysis easier. I'm a bit torn here and there may be a better way.

>>> print(water.atoms)  # what should this be called?
>>> [solute_O, solute_H1, solute_H2]  # maybe this should be a dict?

For a single atom solute the atoms list would still be present but the data within would be identical to the solvation_data of the solute itself. Single atom solutes are now just a special case of multi-atom solutes.

water_O_solute.atoms[0].solvation_data = water_O_solute.solvation_data

I'm sure there are many things I am not considering that will come up later, but as a start, I think this plan will allow the package to be generalized with maximum code reuse. I'd love feedback or suggestions on any aspect of the outline above.

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] make solutions composable so that multi-atom solutes can be constructed systematically
• [x] put guardrails in place to prevent misuse
• [ ] bare minimum rewrite of the documentation

Status

• [ ] Ready to go

Description

This PR adds an analysis module to calculate residence times and an analysis module to calculate solute-solvent networks.

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] Residence module
• [x] Change exponential fit in residence time calculations to 1/e decay point
• [x] Networking module
• [x] Residence testing
• [x] Networking testing
• [x] Residence documentation
• [x] Networking documentation
• [x] Add diluent_composition analysis to Pairing class
• [x] Add module selection kwarg to Solution
• [x] Add from_solution class method to all analysis classes
• [x] Residence and Networking tutorial
• [x] add citations for Networking and Residence codes
• [x] improve documentation for Residence time
  • [x] specify caveats and difference between both implementations

Status

The PR is nearly finished, the main outstanding issues are improved documentation, citations and tutorials.

We should decide on a model for a release schedule, Do we wish to match the MDA core idea and do quarterly (@IAlibay is that right?) releases? Or do we just want to do with major functionality change, ie at your discretion @orioncohen?

If people want updated functionality and bugfixes, they can always clone the current main branch and install with pip install -e .

Raising issue as food for thought.

UPDATE:

This PR now implements a number of quality of life changes and solves issue #31. The proposed multi-atom solute changes will be implemented in another PR. See PR #72 for the new changes!

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] add new testing data with a multi-atom solute
• [x] remove foolish internal numbering scheme of solvated_atoms
• [x] allow solutes to also act as solvents
• [x] replace all column name strings with variables stored in a column_names.py file

Status

• [x] Ready to go

Description

This is intended to be a major PR to handle multi-atom solutes. It relates to issues #47, #31, #66, and #58.

I would like to propose the following outline of new functionality. In this description, I will focus on the outward facing API. I'll use the somewhat trivial case of water as an example.

1. Solution will be renamed to Solute. All references to solute in the current documentation will be renamed to solvated atom or solvated atoms. I think this better captures what the Solute class really is, especially as we expand to multi-atom Solutes.

2. The default initializer for Solute will take only a single atom per residue. It will not support multiple identical atoms on a residue. This will be handled by the more general case. As a result, instantiating a Solute for a single atom remains the same. (note that I have already fixed the case with self-solvation identified in issue #31)

water = u.select_atoms(...)
water_O = u.select_atoms(...)
water_O_solute = Solute(water_O, {"water": water})

4. Additional initializers will be added to instantiate a Solute, these will support multi-atom solutes.

The first will allow the user to stitch together multiple solutes to create a new solute.

water_H1 = u.select_atoms(...)
water_H2 = u.select_atoms(...)
solute_O = Solute(water_O, {"water": water})
solute_H1 = Solute(water_H1, {"water": water})
solute_H2 = Solute(water_H2, {"water": water})

multi_atom_solute = Solute.from_solutes([solute_O, solute_H1, solute_H2])  # maybe this should be a dict?

The second will allow users to simply instantiate a solute from an entire residue (or part of a residue). There may be technical challenges here so this behavior is not guaranteed.

multi_atom_solute = Solute.from_residue(water, {"water": water})

5. To support this, the solvation_data dataframe will have two additional columns added, a "residue" column and a "solute_name" column. All analysis classes will be refactored to operate on the "residue" column rather than the "solvated_atom" column. This will make no difference for single-atom solutes but will allow the analysis classes to generalize easily. I'm not completely sure the "solute_name" column is necessary, but it would be convenient to have.

6. When a multi-atom solute is created all of the solvation_data dataframes from each constituent single-atom solute will be merged together. The "residue" column will group together solvated atoms on the same residue such that the analysis classes can operate on the whole solute. The API for accessing the residence classes will be identical.

multi_atom_solute.coordination_number["water"]   # valid property

7. We will retain all of the single atom Solutes as a property of the multi-atom Solute. This would amount to a rough doubling of the memory footprint, but it would make follow up analysis easier. I'm a bit torn here and there may be a better way.

>>> print(water.atoms)  # what should this be called?
>>> [solute_O, solute_H1, solute_H2]  # maybe this should be a dict?

For a single atom solute the atoms list would still be present but the data within would be identical to the solvation_data of the solute itself. Single atom solutes are now just a special case of multi-atom solutes.

water_O_solute.atoms[0].solvation_data = water_O_solute.solvation_data

I'm sure there are many things I am not considering that will come up later, but as a start, I think this plan will allow the package to be generalized with maximum code reuse. I'd love feedback or suggestions on any aspect of the outline above.

Todos

Notable points that this PR has either accomplished or will accomplish.

• [x] add new testing data with a multi-atom solute
• [x] remove foolish internal numbering scheme of solvated_atoms
• [x] allow solutes to also act as solvents
• [x] replace all column name strings with variables stored in a column_names.py file
• [ ] make solutions composable so that multi-atom solutes can be constructed systematically
• [ ] put guardrails in place to prevent misuse

Status

• [ ] Ready to go

I am using Residence.from_solute(solute) to calculate the residence time between trimers' N and water' O. It always reports the same concatenation issue which seems to be caused by the calculation of auto-covariance (Fig 1). However, when I calculate the residence time between anion and water, there isn't this problem. I add the solvation_data of anion solution (Fig 2) and trimer solution for your reference (Fig 3).

Fig 3

This is split off from PR #78 to address two points the consistency and formatting of the documentation.

Todos:

• [ ] closely read over all documentation for errors
• [ ] make sure all syntax and code styling is consistent
• [ ] enhance aesthetic styling of documentation

Now that MDAKits are live to roll we should work towards registering solvation-analysis as an MDAKit!

See the blog post for more info.

@orionarcher I would be interested to know if you would prefer to just go for it or wait for 0.2.0 (and some conda packages).

AFAIK solvation-analysis already meets all the requirements listed in the white paper.

Description

Provide a brief description of the PR's purpose here.

Todos

Notable points that this PR has either accomplished or will accomplish.

• [ ] TODO 1

Questions

• [ ] Question1

Status

• [ ] Ready to go

This method should dump the core solvation statistics to python dict. It will not contain enough information to reconstitute the Solution.

Brought up in issue #52.