{"action":"opened","issue":{"url":"https://api.github.com/repos/choderalab/alchemy/issues/21","labels_url":"https://api.github.com/repos/choderalab/alchemy/issues/21/labels{/name}","comments_url":"https://api.github.com/repos/choderalab/alchemy/issues/21/comments","events_url":"https://api.github.com/repos/choderalab/alchemy/issues/21/events","html_url":"https://github.com/choderalab/alchemy/issues/21","id":119399465,"number":21,"title":"Proposed API for DualTopologyFactory","user":{"login":"jchodera","id":3656088,"avatar_url":"https://avatars.githubusercontent.com/u/3656088?v=3","gravatar_id":"","url":"https://api.github.com/users/jchodera","html_url":"https://github.com/jchodera","followers_url":"https://api.github.com/users/jchodera/followers","following_url":"https://api.github.com/users/jchodera/following{/other_user}","gists_url":"https://api.github.com/users/jchodera/gists{/gist_id}","starred_url":"https://api.github.com/users/jchodera/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jchodera/subscriptions","organizations_url":"https://api.github.com/users/jchodera/orgs","repos_url":"https://api.github.com/users/jchodera/repos","events_url":"https://api.github.com/users/jchodera/events{/privacy}","received_events_url":"https://api.github.com/users/jchodera/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-11-30T00:28:51Z","updated_at":"2015-11-30T00:28:51Z","closed_at":null,"body":"We need the ability to create OpenMM `System` objects with context parameters that allow us to perform relative free energy calculations between two `System` endpoints.\r\n\r\nWe presume that the user starts with:\r\n*  `System` object for system 1\r\n*  `System` object for system 2\r\n*  a mapping between atoms in systems 1 and 2, where we also require that the positions of atoms listed in this map are *identical* in both sets of positions\r\n\r\n### Proposed API\r\n\r\nHow does this look for an API:\r\n```python\r\nfrom alchemy.relative import DualTopologyFactory\r\n# Create a factory that generates alchemical intermediates.\r\nfactory = DualTopologyFactory(system1, system2, atom_mapping)\r\n# Retrieve the alchemically-modified system.\r\nalchemical_system = factory.createPerturbedSystem()\r\n```\r\nHere `atom_mapping` is a dict that maps atoms in `system1` to `system2`.\r\n\r\nWe can add some other optional arguments to the factory:\r\n* a `context_parameter_prefix` that allows us to specify the prefix prepended to alchemical context parameters (with the default of `lambda`, e.g. `lambda_sterics`, `lambda_electrostatics`); this could avoid parameter namespace collisions if other alchemical components are in use (e.g. alchemical softening of a loop or residues near a binding site through an orthogonal parameter)\r\n* additional optional factory arguments could control the alchemical softcore potential, such as the softness parameters `alpha` (Lennard-Jones) and `beta` (Coulomb) softcore parameters\r\n\r\n### Some questions:\r\n* Do we want to allow the user full control over all of the individual alchemical context parameters (`lambda_sterics`, `lambda_electrostatics`, `lambda_torsion`, `lambda_bonds`, `lambda_angles`), or do we want to have a single `lambda` parameter and let the user specify a set of functions to describe how these various context parameters are slaved to the single controlling function?\r\n* Some of the additional parameters controlling the softcore potential, such as softness parameters (`alpha`, `beta`) and various exponents, could either be hard-coded at `System` creation time, could be left as alchemical parameters the user could change, or could have functions specified that describe how they are slaved to a master `lambda` parameter.  Which one would be more useful?\r\n\r\n### Implementation details\r\nThe current concept is to follow closely the [create_relative_transformation](https://github.com/choderalab/examol/blob/master/examol/dualtopology/create_relative_transformation.py#L44) code from `examol`.  \r\n\r\nAll `Force`s must appear in the same order in each system.  Failure to do so will trigger an exception.\r\n\r\nEach `Force` term in is handled differently:\r\n#### `HarmonicBondForce` and `HarmonicAngleForce`\r\nBonds and angles present in both `system1` and system2` are converted to `Custom*Force`s.\r\nForce constants (`K`) and equilibrium values (`r0`, `theta0`) are linearly interpolated between their initial and final values according to `lambda_bonds` and `lambda_angles`.\r\n#### `PeriodicTorsionForce`\r\nBecause the number and periodicity of Fourier terms can differ between `system1` and `system2`, it seems most appropriate to have `lambda_torsions` produce a linear interpolation of the energies of the two systems.\r\n#### `NonbondedForce`\r\n* Atoms appearing only in one system but not the other will end up as uncharged, noninteracting dummy atoms in those systems, using softcore electrostatics and sterics to create/delete those atoms.\r\n* Any atoms shared between both systems but differing in Lennard-Jones parameters or charges will have *both* sterics and electrostatics use an intermediate softcore form, with softness parameters `alpha` and `beta` controlling this.  \r\n* Any atoms shared between both systems where both Lennard-Jones parameters and charges match between both systems will be treated by normal forces and will not be softcore.\r\n* We are unable to support the reciprocal-space component of PME, requiring us to zero out the charges for any atoms whose charges are .  This means that atoms being created, destroyed, or undergoing mutations will have their charges zeroed out in the PME calculation.  \r\n#### `GBSAOBCForce`\r\nThis will be converted to a `CustomGBForce` implementation.\r\n#### `CustomGBForce`\r\nThis will work only of the energy function and parameter names are the same; otherwise, an `Exception` will be thrown.\r\nParameters will be interpreted between the two systems.\r\nExclusions will be combined from both systems.\r\nExclusions in the shared components of the system must match.\r\n#### Other forces\r\nRight now, we will throw an `Exception`, but it is possible we will want to treat other forces (`MonteCarloBarostat`, `COMMotionRemover`) by checking that all parameters are the same and adding it to the resulting alchemically-modified system\r\n\r\nAnything I have forgotten?"}}