Membrane Builder
================

Create Membrane Builder Project
-------------------------------

Let's walk through how to create a Membrane Builder project. You will need the project ID from a previously created PDB Reader project. For this example, we'll use the project we just created above.

**NOTE:** If you don't include ``pdbreader_project_id``, it will create a membrane-only system.

The following arguments are available for the ``create_project`` method:

* title (str): Project Title
* ff (str): Project force field type (``charmmff``, ``amberff``)
* membrane_type (MembraneType): Membrane type (default: ``MembraneType.BILAYER``)
* pdbreader_project_id (str | list[str]): The project ID(s) of the PDBreader to be used as solute.
  - Pass a single ``str`` for Bilayer, Nanodisc, Vesicle, Micelle, or HexPhase systems.
  - Pass a ``list[str]`` of 1 or 2 project IDs for a Double Bilayer system (upper/lower leaflet order).
  - Omit or pass ``None`` for a membrane-only system.
* amberOptions (dict[str, str]): Amber force field options when ``ff='amberff'`` (default: None)

Example::

   from molcube.membrane_builder.enum import *

   # alt: pdbreader_project_id = pdbreader.projectId
   pdbreader_project_id = '78080ec8-bfcd-4141-8f22-f0ae805374ff'

   # Create Membrane Builder project
   mbuilder = molcube.create_membrane_builder_project()
   assert mbuilder.create_project(title="my_membrane_project",
      pdbreader_project_id=pdbreader_project_id,
      membrane_type=MembraneType.BILAYER, ff='amberff')

   assert mbuilder.align_membrane_protein(option={"align": "ppm"})

You can check the required by the ``generate_lipid_packing()`` method for each membrane type using the ``get_packing_data_form()`` method.

This method takes the ``composition_option (str)`` argument, which can be either ``ratio`` or ``number``. (default: ratio)

::

   >>> lipids, box_margin = mbuilder.get_packing_data_form()
   lipids Form:
   [
     {
       "lipid": "CHL",
       "upRatio": 1,
       "lowRatio": 1
     },
     {
       "lipid": "POPC",
       "upRatio": 4,
       "lowRatio": 4
     }
   ]

   box_margin Form:
   {
     "margin": 20
   }

::

   # Build lipid packing
   assert mbuilder.generate_lipid_packing(lipids, box_margin)

   # Replace lipid packing and build system
   assert mbuilder.replace_packing()

Finally, we will combine the individual components to build the system for molecular dynamics (MD) simulation. The following arguments are available for the method:

* waterMargin(float): water margin of Membrane System (default: 22.5).
* ions (str): Type of ions to use (default: "kcl").
* ionConc (float): Ion concentration (default: 0.15).
* temperature (float): Temperature for the system in Kelvin (default: 310.0).
* useHmr (bool): Whether to use hydrogen mass repartitioning (default: False).
* mdEngines (list[str]): Molecular dynamics engine to use (default: ['openmm']).

**Bilayer** additional options:

* useHydration (bool): Use hydration number method instead of ``waterMargin`` (default: False).
* hydration_number (int): Number of water molecules per one lipid molecule (default: 50).

The available options for ions and mdEngines are as follows:

* ions / interIons: ['kcl', 'nacl', 'cacl2', 'mgcl2']
* lipaIons / coreIons: ['cal', 'CAL', 'mg', 'MG']
* mdEngines: ['openmm', 'amber', 'gromacs', 'namd', 'genesis', 'desmond']

::

   assert mbuilder.generate_system(ions='kcl', mdEngines=['openmm', 'gromacs'])