mempro 0.2.1__tar.gz → 0.3.0__tar.gz

{mempro-0.2.1 → mempro-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempro
-Version: 0.2.1
+Version: 0.3.0
 Summary: Membrane Protein Orientation in Lipid Bilayers
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -14,6 +14,8 @@ Dynamic: license-file
 # MemPrO
 Membrane Protein Orientation in Lipid Bilayers. The paper associated with this code can be found [here](https://doi.org/10.1021/acs.jctc.5c01433).
 
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pstansfeld/MemPrO/blob/main/MemPrO_Colab.ipynb)
+
 Code and parameters from the following were used to help write this code:
 
 **Insane:**
@@ -56,7 +58,9 @@ pip install "matplotlib>=3.8.4"
 
 The Martini 3 force field file (`martini_v3.itp`) is included in `mempro/`. To use a different one, supply its path with the `-itp` flag; the standard file can be downloaded from [here](https://cgmartini.nl/docs/downloads/force-field-parameters/martini3/particle-definitions.html).
 
-MemPrO is also accessible on Google Colab via the link [ADD LINK]. The Colab will contain instructions for use. (Currently the Colab is WIP and this will be updated.)
+### Google Colab
+
+MemPrO can also be run without installing anything locally, using the [MemPrO Colab notebook](https://colab.research.google.com/github/pstansfeld/MemPrO/blob/main/MemPrO_Colab.ipynb). It installs MemPrO from PyPI, orients a structure from the PDB, AlphaFold DB or your own upload, shows the results (including a 3D view of the top-ranked orientation), and can optionally predict membrane deformations with MemPrOD. It runs on both CPU and GPU runtimes.
 
 ## Running MemPrO
 
@@ -72,7 +76,7 @@ python PATH/TO/MemPrO.py -f input_file.pdb
 mempro -f input_file.pdb
 ```
 
-No environment variables are required. By default MemPrO will use all available CPU cores and look for `Insane4MemPrO.py` and `martini_v3.itp` in the same directory as the script (or the installed package directory). These paths can be overridden with the `-insane` and `-itp` flags if needed.
+No environment variables are required. By default MemPrO will use a GPU if JAX can see one, otherwise one CPU device per performance core (see `-nc`), and will look for `Insane4MemPrO.py` and `martini_v3.itp` in the same directory as the script (or the installed package directory). These paths can be overridden with the `-insane` and `-itp` flags if needed.
 
 Compiled code is cached in `~/.cache/mempro/jax`, so runs after the first one start about 15 s faster. Set `JAX_COMPILATION_CACHE_DIR` to put the cache somewhere else, or `MEMPRO_NO_JAX_CACHE=1` to turn it off.
 
@@ -82,6 +86,8 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 * **orientation.txt** — Contains general information about all of the final minima. In general rank 1 is the best orientation, however there are cases where this is not true. `orientation.txt` can then be used to determine the best orientation.
 
+* **orientations.pdb** — All final orientations in a single PDB file, one model per rank, ordered by rank.
+
 * **local_minima_orientation.png** — A representation of how spread out the local minima are. The more white the image, the more confidence can be placed in rank 1. This is only true in general and there are some cases where this can be safely ignored.
 
 * **local_minima_potential.png** — A representation of the potential of the final configuration from a given starting configuration. This complements `local_minima_orientation.png` but in general does not provide much additional information.
@@ -93,7 +99,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
   * `PG_potential_curve.png` — The potential curve for the position of the PG cell wall. Only produced with `-pg`.
   * `cross-section_area_curve.png` — The cross-sectional area of the segment of the protein passing through the PG layer. Only produced with `-pg`.
   * `Z_potential_curve.png` — Potential against Z position of the final orientation. Gives an idea of the nature of the minima.
-  * `curv_potential_curve.png` — Potential against global membrane curvature for the final orientation. Can indicate whether curvature minimisation should be used.
+  * `curv_potential_curve.png` — Potential against global membrane curvature for the final orientation. Can indicate whether curvature minimisation should be used. Not produced with `-dm`.
 
 ## Flags
 
@@ -107,7 +113,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-ng, --grid_size** — Number of initial starting configurations. Defaults to 36. For best efficiency this should be a multiple of the number of CPUs being used. More starting configurations sample the space of minima better, but there are diminishing returns and generally no more than 40 are needed.
 
-**-nc, --num_cpus** — Number of CPU cores to use. Defaults to the number of performance cores where the system reports them (e.g. 4 on an Apple M4, whose 6 efficiency cores would slow each batch down), otherwise all available cores. For best performance with `-ng`, set `-nc` to a value that divides `-ng` evenly.
+**-nc, --num_cpus** — Number of CPU cores to use. Defaults to the number of performance cores where the system reports them (currently macOS, e.g. 4 on an Apple M4, whose 6 efficiency cores would slow each batch down), otherwise all available cores. For best performance with `-ng`, set `-nc` to a value that divides `-ng` evenly.
 
 **-dev, --device** — Device to run on: `auto` (default; GPU if JAX can see one, otherwise CPU), `cpu` or `gpu`. On GPU, all starting configurations are minimised together in a single batch. GPU support needs `pip install "mempro[gpu]"` (Linux, NVIDIA).
 
@@ -115,6 +121,8 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-rank, --rank** — Ranking method for minima: `h` ranks by percentage hits, `p` ranks by potential, `auto` (default) ranks by a value calculated from approximate minima depth and potential.
 
+**-seed, --seed** — Seed for the random number generators. Runs with the same seed, input and flags give identical results, provided the number of devices (`-nc`, or the number of GPUs) is also the same. Default is unseeded.
+
 **-dm, --dual_membrane** — Toggles dual membrane minimisation. Splits the membrane into an inner and outer membrane and minimises the distance between them. Only use this if your protein spans the periplasm or is a gap junction etc.
 
 **-ch, --charge** — Partial charge of the (inner) membrane. The value corresponds to the average charge on a lipid divided by the average area per lipid, representing the average charge across the bilayer sheet. For an E. coli inner membrane this is around -0.008. Default is 0, which gives the best performance in most cases.
@@ -147,7 +155,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-insane, --insane_path** — Path to `Insane4MemPrO.py`. Defaults to the same directory as `MemPrO.py` (or the installed package directory). Only required when using `-bd`.
 
-**-bd, --build_system** — Number of final ranked configurations to build as CG MD-ready systems using Insane4MemPrO. Currently only works with coarse grain input files.
+**-bd, --build_system** — Number of final ranked configurations to build as CG MD-ready systems using Insane4MemPrO. Default is 0 (no systems built). Currently only works with coarse grain input files.
 
 **-bd_args, --build_arguments** — Arguments to pass to Insane4MemPrO, primarily lipid composition, solvent type etc. Required when using `-bd`.
 
@@ -167,10 +175,16 @@ Orient `input_file.pdb` on a grid of 40 starting configurations with 150 minimis
 python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150
 ```
 
-Orient with global curvature minimisation and write per-bead potentials to b-factors:
+Orient with global curvature minimisation:
+
+```
+python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -c
+```
+
+Orient and write per-bead potentials to b-factors (`-wb` is not compatible with `-c`):
 
 ```
-python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -c -wb
+python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -wb
 ```
 
 Orient with a dual membrane system, then build the top 2 ranked configurations as CG systems. The inner membrane contains POPE, POPG and CARD; the outer membrane contains LIPA:
@@ -255,29 +269,29 @@ MemPrO comes with Insane4MemPrO, a CG system builder based on [Insane](https://g
 
 #### Peptidoglycan layer options
 
-**-pgl** — (Optional) Number of PG layers to place at `-pgl_z`.
+**-pgl** — (Default: 0) Number of PG layers to place at `-pgl_z`.
 
-**-pgl_z** — (Optional) Z position of the PG layer relative to the centre of the periplasmic space.
+**-pgl_z** — (Default: 0) Z position of the PG layer relative to the centre of the periplasmic space.
 
-**-cper** — (Optional) Percentage of cross-links.
+**-cper** — (Default: 0.4) Percentage of cross-links.
 
-**-lper** — (Optional) Percentage of cross-links that are between layers.
+**-lper** — (Default: 0.1) Percentage of cross-links that are between layers.
 
-**-per33** — (Optional) Percentage of 3-3 cross-links; all other cross-links will be 3-4.
+**-per33** — (Default: 0.03) Percentage of 3-3 cross-links; all other cross-links will be 3-4.
 
-**-oper** — (Optional) Percentage chance of a monomer linking with an oligomer. (Actual chance of link is `cper * oper`.)
+**-oper** — (Default: 1) Percentage chance of a monomer linking with an oligomer. (Actual chance of link is `cper * oper`.)
 
 **-gdist** — (Default: 0.75,4,8.9,0.25,10,45) Distribution of glycan strand lengths. Format as `weight1,stddev1,mean1,weight2,...` where each triple describes a Gaussian. The sum of these Gaussians forms the distribution.
 
 #### Protein options
 
-**-fudge** — (Default: 0.3) Fudge factor for allowing lipid-protein overlap.
+**-fudge** — (Default: 0.3) Fudge factor for allowing lipid-protein overlap. A value of 0.15 is recommended when using `-def`.
 
 #### Solvent options
 
 **-sol** — (Required) Solvent type.
 
-**-sold** — (Default: 0.5) Solvent packing density.
+**-sold** — (Default: 0.5) Solvent diameter.
 
 **-solr** — (Default: 0.1) Magnitude of random deviations to solvent positions.
 
@@ -331,7 +345,7 @@ More detailed tutorials are available [here](Insane4MemPrO_tutorials.md).
 
 If your protein hasn't oriented correctly there are a number of things to try:
 
-* Check all orientations by loading `orientations.pdb` and reviewing `orientations.txt`. The correct orientation may not be rank 1.
+* Check all orientations by loading `orientations.pdb` and reviewing `orientation.txt`. The correct orientation may not be rank 1.
 * Check `curv_potential_curve.png` to see if your protein prefers a curved membrane. If so, using `-c` will help.
 * Check the PDB file for missing atoms or residues, which can cause the surface to be incorrectly evaluated. Missing atoms should be fixed before orientation.
 * Using `-wb` can be helpful for diagnosing missing atoms — it writes the potential contribution of each residue as a b-factor, viewable in PyMOL.

{mempro-0.2.1 → mempro-0.3.0}/README.md

@@ -1,6 +1,8 @@
 # MemPrO
 Membrane Protein Orientation in Lipid Bilayers. The paper associated with this code can be found [here](https://doi.org/10.1021/acs.jctc.5c01433).
 
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pstansfeld/MemPrO/blob/main/MemPrO_Colab.ipynb)
+
 Code and parameters from the following were used to help write this code:
 
 **Insane:**
@@ -43,7 +45,9 @@ pip install "matplotlib>=3.8.4"
 
 The Martini 3 force field file (`martini_v3.itp`) is included in `mempro/`. To use a different one, supply its path with the `-itp` flag; the standard file can be downloaded from [here](https://cgmartini.nl/docs/downloads/force-field-parameters/martini3/particle-definitions.html).
 
-MemPrO is also accessible on Google Colab via the link [ADD LINK]. The Colab will contain instructions for use. (Currently the Colab is WIP and this will be updated.)
+### Google Colab
+
+MemPrO can also be run without installing anything locally, using the [MemPrO Colab notebook](https://colab.research.google.com/github/pstansfeld/MemPrO/blob/main/MemPrO_Colab.ipynb). It installs MemPrO from PyPI, orients a structure from the PDB, AlphaFold DB or your own upload, shows the results (including a 3D view of the top-ranked orientation), and can optionally predict membrane deformations with MemPrOD. It runs on both CPU and GPU runtimes.
 
 ## Running MemPrO
 
@@ -59,7 +63,7 @@ python PATH/TO/MemPrO.py -f input_file.pdb
 mempro -f input_file.pdb
 ```
 
-No environment variables are required. By default MemPrO will use all available CPU cores and look for `Insane4MemPrO.py` and `martini_v3.itp` in the same directory as the script (or the installed package directory). These paths can be overridden with the `-insane` and `-itp` flags if needed.
+No environment variables are required. By default MemPrO will use a GPU if JAX can see one, otherwise one CPU device per performance core (see `-nc`), and will look for `Insane4MemPrO.py` and `martini_v3.itp` in the same directory as the script (or the installed package directory). These paths can be overridden with the `-insane` and `-itp` flags if needed.
 
 Compiled code is cached in `~/.cache/mempro/jax`, so runs after the first one start about 15 s faster. Set `JAX_COMPILATION_CACHE_DIR` to put the cache somewhere else, or `MEMPRO_NO_JAX_CACHE=1` to turn it off.
 
@@ -69,6 +73,8 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 * **orientation.txt** — Contains general information about all of the final minima. In general rank 1 is the best orientation, however there are cases where this is not true. `orientation.txt` can then be used to determine the best orientation.
 
+* **orientations.pdb** — All final orientations in a single PDB file, one model per rank, ordered by rank.
+
 * **local_minima_orientation.png** — A representation of how spread out the local minima are. The more white the image, the more confidence can be placed in rank 1. This is only true in general and there are some cases where this can be safely ignored.
 
 * **local_minima_potential.png** — A representation of the potential of the final configuration from a given starting configuration. This complements `local_minima_orientation.png` but in general does not provide much additional information.
@@ -80,7 +86,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
   * `PG_potential_curve.png` — The potential curve for the position of the PG cell wall. Only produced with `-pg`.
   * `cross-section_area_curve.png` — The cross-sectional area of the segment of the protein passing through the PG layer. Only produced with `-pg`.
   * `Z_potential_curve.png` — Potential against Z position of the final orientation. Gives an idea of the nature of the minima.
-  * `curv_potential_curve.png` — Potential against global membrane curvature for the final orientation. Can indicate whether curvature minimisation should be used.
+  * `curv_potential_curve.png` — Potential against global membrane curvature for the final orientation. Can indicate whether curvature minimisation should be used. Not produced with `-dm`.
 
 ## Flags
 
@@ -94,7 +100,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-ng, --grid_size** — Number of initial starting configurations. Defaults to 36. For best efficiency this should be a multiple of the number of CPUs being used. More starting configurations sample the space of minima better, but there are diminishing returns and generally no more than 40 are needed.
 
-**-nc, --num_cpus** — Number of CPU cores to use. Defaults to the number of performance cores where the system reports them (e.g. 4 on an Apple M4, whose 6 efficiency cores would slow each batch down), otherwise all available cores. For best performance with `-ng`, set `-nc` to a value that divides `-ng` evenly.
+**-nc, --num_cpus** — Number of CPU cores to use. Defaults to the number of performance cores where the system reports them (currently macOS, e.g. 4 on an Apple M4, whose 6 efficiency cores would slow each batch down), otherwise all available cores. For best performance with `-ng`, set `-nc` to a value that divides `-ng` evenly.
 
 **-dev, --device** — Device to run on: `auto` (default; GPU if JAX can see one, otherwise CPU), `cpu` or `gpu`. On GPU, all starting configurations are minimised together in a single batch. GPU support needs `pip install "mempro[gpu]"` (Linux, NVIDIA).
 
@@ -102,6 +108,8 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-rank, --rank** — Ranking method for minima: `h` ranks by percentage hits, `p` ranks by potential, `auto` (default) ranks by a value calculated from approximate minima depth and potential.
 
+**-seed, --seed** — Seed for the random number generators. Runs with the same seed, input and flags give identical results, provided the number of devices (`-nc`, or the number of GPUs) is also the same. Default is unseeded.
+
 **-dm, --dual_membrane** — Toggles dual membrane minimisation. Splits the membrane into an inner and outer membrane and minimises the distance between them. Only use this if your protein spans the periplasm or is a gap junction etc.
 
 **-ch, --charge** — Partial charge of the (inner) membrane. The value corresponds to the average charge on a lipid divided by the average area per lipid, representing the average charge across the bilayer sheet. For an E. coli inner membrane this is around -0.008. Default is 0, which gives the best performance in most cases.
@@ -134,7 +142,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-insane, --insane_path** — Path to `Insane4MemPrO.py`. Defaults to the same directory as `MemPrO.py` (or the installed package directory). Only required when using `-bd`.
 
-**-bd, --build_system** — Number of final ranked configurations to build as CG MD-ready systems using Insane4MemPrO. Currently only works with coarse grain input files.
+**-bd, --build_system** — Number of final ranked configurations to build as CG MD-ready systems using Insane4MemPrO. Default is 0 (no systems built). Currently only works with coarse grain input files.
 
 **-bd_args, --build_arguments** — Arguments to pass to Insane4MemPrO, primarily lipid composition, solvent type etc. Required when using `-bd`.
 
@@ -154,10 +162,16 @@ Orient `input_file.pdb` on a grid of 40 starting configurations with 150 minimis
 python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150
 ```
 
-Orient with global curvature minimisation and write per-bead potentials to b-factors:
+Orient with global curvature minimisation:
+
+```
+python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -c
+```
+
+Orient and write per-bead potentials to b-factors (`-wb` is not compatible with `-c`):
 
 ```
-python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -c -wb
+python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -wb
 ```
 
 Orient with a dual membrane system, then build the top 2 ranked configurations as CG systems. The inner membrane contains POPE, POPG and CARD; the outer membrane contains LIPA:
@@ -242,29 +256,29 @@ MemPrO comes with Insane4MemPrO, a CG system builder based on [Insane](https://g
 
 #### Peptidoglycan layer options
 
-**-pgl** — (Optional) Number of PG layers to place at `-pgl_z`.
+**-pgl** — (Default: 0) Number of PG layers to place at `-pgl_z`.
 
-**-pgl_z** — (Optional) Z position of the PG layer relative to the centre of the periplasmic space.
+**-pgl_z** — (Default: 0) Z position of the PG layer relative to the centre of the periplasmic space.
 
-**-cper** — (Optional) Percentage of cross-links.
+**-cper** — (Default: 0.4) Percentage of cross-links.
 
-**-lper** — (Optional) Percentage of cross-links that are between layers.
+**-lper** — (Default: 0.1) Percentage of cross-links that are between layers.
 
-**-per33** — (Optional) Percentage of 3-3 cross-links; all other cross-links will be 3-4.
+**-per33** — (Default: 0.03) Percentage of 3-3 cross-links; all other cross-links will be 3-4.
 
-**-oper** — (Optional) Percentage chance of a monomer linking with an oligomer. (Actual chance of link is `cper * oper`.)
+**-oper** — (Default: 1) Percentage chance of a monomer linking with an oligomer. (Actual chance of link is `cper * oper`.)
 
 **-gdist** — (Default: 0.75,4,8.9,0.25,10,45) Distribution of glycan strand lengths. Format as `weight1,stddev1,mean1,weight2,...` where each triple describes a Gaussian. The sum of these Gaussians forms the distribution.
 
 #### Protein options
 
-**-fudge** — (Default: 0.3) Fudge factor for allowing lipid-protein overlap.
+**-fudge** — (Default: 0.3) Fudge factor for allowing lipid-protein overlap. A value of 0.15 is recommended when using `-def`.
 
 #### Solvent options
 
 **-sol** — (Required) Solvent type.
 
-**-sold** — (Default: 0.5) Solvent packing density.
+**-sold** — (Default: 0.5) Solvent diameter.
 
 **-solr** — (Default: 0.1) Magnitude of random deviations to solvent positions.
 
@@ -318,7 +332,7 @@ More detailed tutorials are available [here](Insane4MemPrO_tutorials.md).
 
 If your protein hasn't oriented correctly there are a number of things to try:
 
-* Check all orientations by loading `orientations.pdb` and reviewing `orientations.txt`. The correct orientation may not be rank 1.
+* Check all orientations by loading `orientations.pdb` and reviewing `orientation.txt`. The correct orientation may not be rank 1.
 * Check `curv_potential_curve.png` to see if your protein prefers a curved membrane. If so, using `-c` will help.
 * Check the PDB file for missing atoms or residues, which can cause the surface to be incorrectly evaluated. Missing atoms should be fixed before orientation.
 * Using `-wb` can be helpful for diagnosing missing atoms — it writes the potential contribution of each residue as a b-factor, viewable in PyMOL.

{mempro-0.2.1 → mempro-0.3.0}/mempro/MemPrO.py

@@ -13,6 +13,8 @@ from functools import partial, lru_cache
 import datetime
 from jax import tree_util
 import shutil
+import shlex
+import sys
 from collections import defaultdict
 
 PATH_TO_INSANE = os.environ.get("PATH_TO_INSANE", "")
@@ -365,17 +367,21 @@ class PDB_helper:
 		with open(os.path.join(self.fn), "r") as lfile:
 			content = lfile.read().split("\n")
 
-		# Group atom lines by (residue name, residue ID)
-		residue_atoms = defaultdict(list)
+		# Group consecutive atom lines into residues. A residue ends when the residue name, chain or
+		# number changes, so repeated residue numbers in a chain (e.g. martinize2's default
+		# renumbering of multi-chain proteins) stay separate residues. write_oriented() writes one
+		# line per bead in file order, so there must be exactly one bead per valid ATOM line.
+		residues = []
+		prev_key = None
 		for c in content:
 			if len(c) > 54 and "[" not in c and c.startswith("ATOM"):
-				resname = c[17:21].strip()
-				resid = int(c[22:26].strip())
-				chain_id = c[21].strip()
-				residue_atoms[(resname, chain_id, resid)].append(c)
+				key = (c[17:21].strip(), c[21].strip(), c[22:27])
+				if key != prev_key:
+					residues.append((key[0], int(c[22:26].strip()), []))
+					prev_key = key
+				residues[-1][2].append(c)
 
-		for (resname, chain_id, resid), atoms in residue_atoms.items():
-			original_resname = resname
+		for resname, resid, atoms in residues:
 			if resname not in Reses:
 				print(f"Unknown residue {resname}, using UNK")
 				resname = "UNK"
@@ -385,7 +391,7 @@ class PDB_helper:
 			# Collect atom positions
 			atom_pos_list = []
 			atom_bval_list = []
-			atom_nums = []
+			atom_names = []
 
 			for c in atoms:
 				try:
@@ -393,13 +399,12 @@ class PDB_helper:
 					y = float(c[38:46].strip())
 					z = float(c[46:54].strip())
 					b = float(c[60:66].strip())
-					atom_num = int(c[22:26].strip())
 					pos = np.array([x, y, z])
 
 					if not np.any(np.isnan(pos)):
 						atom_pos_list.append(pos)
 						atom_bval_list.append(b)
-						atom_nums.append(atom_num)
+						atom_names.append(c[12:16].strip())
 				except ValueError:
 					continue
 
@@ -407,36 +412,25 @@ class PDB_helper:
 				print(f"Skipping residue {resname} {resid} due to no valid positions.")
 				continue
 
-			# Fallback mean values
-			mean_pos = np.mean(atom_pos_list, axis=0)
-			mean_b = np.mean(atom_bval_list) if atom_bval_list else 0.0
-
-			# Use quick hack: match bead types with atom positions by order
-			if len(bead_list) != len(atom_pos_list):
-				#print(f"Mismatch in bead count vs atom count for {resname} {resid}. Using mean positions. Expecting {len(bead_list)}, found {len(atom_pos_list)}")
-				if resname == "UNK":
-					bead_list = np.arange(len(atom_pos_list))
-				else:
-					print(atom_pos_list)
-					print(f"Mismatch in bead count vs atom count for {resname} {resid}. Using mean positions. Expecting {len(bead_list)}, found {len(atom_pos_list)}")
-				for bead_type in bead_list:
-					if resname == "UNK":
-						bead_index == 22
-					else:
-						bead_index = Beadtype.get(bead_type, -1)
-					if bead_index == -1:
-						raise ValueError(f"Unknown bead type: {bead_type}")
-					self.bead_types.append(bead_index)
-					self.reses.append(res_index)
-					if resname == "UNK":
-						self.poses.append(atom_pos_list[bead_type])
-						self.b_vals.append(atom_bval_list[bead_type])
+			if resname == "UNK":
+				res_bead_types = ["GHOST"]*len(atom_pos_list)
+			elif len(bead_list) == len(atom_pos_list):
+				res_bead_types = bead_list
+			else:
+				# Match beads by Martini name (BB, SC1, SC2, ...), falling back to file order
+				print(f"Mismatch in bead count vs atom count for {resname} {resid}. Expecting {len(bead_list)}, found {len(atom_pos_list)}. Matching beads by name.")
+				res_bead_types = []
+				for j, name in enumerate(atom_names):
+					if name == "BB":
+						k = 0
+					elif name.startswith("SC") and name[2:].isdigit():
+						k = int(name[2:])
 					else:
-						self.poses.append(mean_pos)
-						self.b_vals.append(mean_b)
-				continue
+						k = j
+					res_bead_types.append(bead_list[min(k, len(bead_list)-1)])
 
-			for bead_type, pos, b_val in zip(bead_list, atom_pos_list, atom_bval_list):
+			in_range = self.ranges.size != 0 and self.in_ranges(resid)
+			for bead_type, pos, b_val in zip(res_bead_types, atom_pos_list, atom_bval_list):
 				bead_index = Beadtype.get(bead_type, -1)
 				if bead_index == -1:
 					raise ValueError(f"Unknown bead type: {bead_type}")
@@ -445,7 +439,6 @@ class PDB_helper:
 				self.poses.append(pos)
 
 				if self.ranges.size != 0:
-					in_range = any(self.in_ranges(num) for num in atom_nums)
 					self.b_vals.append(1.0 if in_range else 0.0)
 				else:
 					self.b_vals.append(b_val)
@@ -2571,7 +2564,7 @@ class MemBrain:
 		
 		
 	#Builds a CG system using insane
-	def build_oriented(self,orient_dir,build_args):
+	def build_oriented(self,orient_dir,build_args,insane_path):
 		mins = np.array(self.minima)
 		no_mins = (mins.shape[0]//5)
 		min_poses = mins[:no_mins]
@@ -2594,14 +2587,14 @@ class MemBrain:
 			curv_str = " -curv "+str(10*np.abs(min_curvs[i]))+",0.1,"+str(np.sign(min_curvs[i]-1e-9))
 			print("Building rank "+str(i+1)+" with Insane4MemPrO:")
 			cg_sys_dir = rank_dir+"CG_System_rank_"+str(i+1)+"/"
-			run_str = "python "+PATH_TO_INSANE+" "+build_args.strip()+" -o "+cg_sys_dir+"CG-system.gro -p "+cg_sys_dir+"topol.top -f "+cg_sys_dir+"protein-cg.pdb "+"-x "+str(x_range)+" -y "+str(y_range)+" -z "+str(z_range)+curv_str
+			run_str = shlex.quote(sys.executable)+" "+shlex.quote(insane_path)+" "+build_args.strip()+" -o "+shlex.quote(cg_sys_dir+"CG-system.gro")+" -p "+shlex.quote(cg_sys_dir+"topol.top")+" -f "+shlex.quote(cg_sys_dir+"protein-cg.pdb")+" -x "+str(x_range)+" -y "+str(y_range)+" -z "+str(z_range)+curv_str
 			if(zdist > 1e-6):
 				run_str += " -ps "+str(zdist)
 			if(self.pg_layer_pred):
 				ps = self.pg_poses[i][0]
 				xs_pg = self.pg_poses[i][1]
 				pg_pos = -xs_pg[jnp.argmin(ps)]
-				run_str += " -pgl_z "+str(pg_pos/10.0)+" -o_f "+cg_sys_dir
+				run_str += " -pgl_z "+str(pg_pos/10.0)+" -o_f "+shlex.quote(cg_sys_dir)
 				#print()
 			err_val = os.system(run_str)
 			if(err_val != 0):
@@ -3478,14 +3471,14 @@ def main():
 	os.environ["TF_CPP_MIN_LOG_LEVEL"]="3"
 
 	#Reading command line args
-	parser = argparse.ArgumentParser(prog="MemPrO",description="Orients a protein in a membrane. Currently only for E-coli membranes, but this will change in future updates. Currently flags -c -c_ni -ps -fc are WIP, these can still be used at the your own peril.")
+	parser = argparse.ArgumentParser(prog="MemPrO",description="Orients a protein in a membrane. Currently only for E-coli membranes, but this will change in future updates.")
 	parser.add_argument("-f", "--file_name",help = "Input file name (.pdb)")
 	parser.add_argument("-o","--output",help="Name of the output directory (Default: Orient)")
 	parser.add_argument("-ni","--iters",help="Number of minimisation iterations (Default: 150)")
 	parser.set_defaults(iters=150)
 	parser.add_argument("-ng","--grid_size",help="Number of starting configurations (Default: 36)")
 	parser.set_defaults(grid_size=36)
-	parser.add_argument("-nc","--num_cpus",help="Number of CPU cores to use (Default: all available)",type=int)
+	parser.add_argument("-nc","--num_cpus",help="Number of CPU cores to use (Default: performance cores on macOS, otherwise all available)",type=int)
 	parser.set_defaults(num_cpus=None)
 	parser.add_argument("-dev","--device",help="Device to run on: auto (GPU if available, otherwise CPU), cpu or gpu (Default: auto)",choices=["auto","cpu","gpu"])
 	parser.set_defaults(device="auto")
@@ -3508,7 +3501,7 @@ def main():
 	parser.add_argument("-itp","--itp_file",help="Path to force field (martini_v3.itp)")
 	parser.set_defaults(itp_file=_default_itp)
 	parser.add_argument("-insane","--insane_path",help="Path to Insane4MemPrO.py")
-	parser.set_defaults(insane_path=_default_insane)
+	parser.set_defaults(insane_path=PATH_TO_INSANE or _default_insane)
 	parser.add_argument("-bd","--build_system",help = "Build a MD ready CG-system for ranks < n (Default: n=0)")
 	parser.set_defaults(build_system=0)
 	parser.add_argument("-bd_args","--build_arguments",help="Arguments to pass to insane when building system")
@@ -3535,12 +3528,21 @@ def main():
 	parser.set_defaults(write_bfactors=False)
 	parser.add_argument("-rank","--rank",help="Ranking method: auto (default), h (hits), p (potential)")
 	parser.set_defaults(rank="auto")
+	parser.add_argument("-seed","--seed",type=int,help="Seed for the random number generators, for reproducible runs. Results also depend on the number of devices (-nc) (Default: unseeded)")
+	parser.set_defaults(seed=None)
 	args = parser.parse_args()
 
 	if args.file_name is None:
 		parser.print_help()
 		sys.exit(0)
 
+	#All random draws in MemPrO use NumPy's global generator
+	if args.seed is not None:
+		if not 0 <= args.seed < 2**32:
+			print("ERROR: Could not read value of -seed. Must be an integer between 0 and 2^32-1.")
+			exit()
+		np.random.seed(args.seed)
+
 	fliper = 1
 	if args.flip:
 		fliper = -1

{mempro-0.2.1 → mempro-0.3.0}/mempro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempro
-Version: 0.2.1
+Version: 0.3.0
 Summary: Membrane Protein Orientation in Lipid Bilayers
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -14,6 +14,8 @@ Dynamic: license-file
 # MemPrO
 Membrane Protein Orientation in Lipid Bilayers. The paper associated with this code can be found [here](https://doi.org/10.1021/acs.jctc.5c01433).
 
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pstansfeld/MemPrO/blob/main/MemPrO_Colab.ipynb)
+
 Code and parameters from the following were used to help write this code:
 
 **Insane:**
@@ -56,7 +58,9 @@ pip install "matplotlib>=3.8.4"
 
 The Martini 3 force field file (`martini_v3.itp`) is included in `mempro/`. To use a different one, supply its path with the `-itp` flag; the standard file can be downloaded from [here](https://cgmartini.nl/docs/downloads/force-field-parameters/martini3/particle-definitions.html).
 
-MemPrO is also accessible on Google Colab via the link [ADD LINK]. The Colab will contain instructions for use. (Currently the Colab is WIP and this will be updated.)
+### Google Colab
+
+MemPrO can also be run without installing anything locally, using the [MemPrO Colab notebook](https://colab.research.google.com/github/pstansfeld/MemPrO/blob/main/MemPrO_Colab.ipynb). It installs MemPrO from PyPI, orients a structure from the PDB, AlphaFold DB or your own upload, shows the results (including a 3D view of the top-ranked orientation), and can optionally predict membrane deformations with MemPrOD. It runs on both CPU and GPU runtimes.
 
 ## Running MemPrO
 
@@ -72,7 +76,7 @@ python PATH/TO/MemPrO.py -f input_file.pdb
 mempro -f input_file.pdb
 ```
 
-No environment variables are required. By default MemPrO will use all available CPU cores and look for `Insane4MemPrO.py` and `martini_v3.itp` in the same directory as the script (or the installed package directory). These paths can be overridden with the `-insane` and `-itp` flags if needed.
+No environment variables are required. By default MemPrO will use a GPU if JAX can see one, otherwise one CPU device per performance core (see `-nc`), and will look for `Insane4MemPrO.py` and `martini_v3.itp` in the same directory as the script (or the installed package directory). These paths can be overridden with the `-insane` and `-itp` flags if needed.
 
 Compiled code is cached in `~/.cache/mempro/jax`, so runs after the first one start about 15 s faster. Set `JAX_COMPILATION_CACHE_DIR` to put the cache somewhere else, or `MEMPRO_NO_JAX_CACHE=1` to turn it off.
 
@@ -82,6 +86,8 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 * **orientation.txt** — Contains general information about all of the final minima. In general rank 1 is the best orientation, however there are cases where this is not true. `orientation.txt` can then be used to determine the best orientation.
 
+* **orientations.pdb** — All final orientations in a single PDB file, one model per rank, ordered by rank.
+
 * **local_minima_orientation.png** — A representation of how spread out the local minima are. The more white the image, the more confidence can be placed in rank 1. This is only true in general and there are some cases where this can be safely ignored.
 
 * **local_minima_potential.png** — A representation of the potential of the final configuration from a given starting configuration. This complements `local_minima_orientation.png` but in general does not provide much additional information.
@@ -93,7 +99,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
   * `PG_potential_curve.png` — The potential curve for the position of the PG cell wall. Only produced with `-pg`.
   * `cross-section_area_curve.png` — The cross-sectional area of the segment of the protein passing through the PG layer. Only produced with `-pg`.
   * `Z_potential_curve.png` — Potential against Z position of the final orientation. Gives an idea of the nature of the minima.
-  * `curv_potential_curve.png` — Potential against global membrane curvature for the final orientation. Can indicate whether curvature minimisation should be used.
+  * `curv_potential_curve.png` — Potential against global membrane curvature for the final orientation. Can indicate whether curvature minimisation should be used. Not produced with `-dm`.
 
 ## Flags
 
@@ -107,7 +113,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-ng, --grid_size** — Number of initial starting configurations. Defaults to 36. For best efficiency this should be a multiple of the number of CPUs being used. More starting configurations sample the space of minima better, but there are diminishing returns and generally no more than 40 are needed.
 
-**-nc, --num_cpus** — Number of CPU cores to use. Defaults to the number of performance cores where the system reports them (e.g. 4 on an Apple M4, whose 6 efficiency cores would slow each batch down), otherwise all available cores. For best performance with `-ng`, set `-nc` to a value that divides `-ng` evenly.
+**-nc, --num_cpus** — Number of CPU cores to use. Defaults to the number of performance cores where the system reports them (currently macOS, e.g. 4 on an Apple M4, whose 6 efficiency cores would slow each batch down), otherwise all available cores. For best performance with `-ng`, set `-nc` to a value that divides `-ng` evenly.
 
 **-dev, --device** — Device to run on: `auto` (default; GPU if JAX can see one, otherwise CPU), `cpu` or `gpu`. On GPU, all starting configurations are minimised together in a single batch. GPU support needs `pip install "mempro[gpu]"` (Linux, NVIDIA).
 
@@ -115,6 +121,8 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-rank, --rank** — Ranking method for minima: `h` ranks by percentage hits, `p` ranks by potential, `auto` (default) ranks by a value calculated from approximate minima depth and potential.
 
+**-seed, --seed** — Seed for the random number generators. Runs with the same seed, input and flags give identical results, provided the number of devices (`-nc`, or the number of GPUs) is also the same. Default is unseeded.
+
 **-dm, --dual_membrane** — Toggles dual membrane minimisation. Splits the membrane into an inner and outer membrane and minimises the distance between them. Only use this if your protein spans the periplasm or is a gap junction etc.
 
 **-ch, --charge** — Partial charge of the (inner) membrane. The value corresponds to the average charge on a lipid divided by the average area per lipid, representing the average charge across the bilayer sheet. For an E. coli inner membrane this is around -0.008. Default is 0, which gives the best performance in most cases.
@@ -147,7 +155,7 @@ MemPrO is intended to be run on PDB files, and will output the following files:
 
 **-insane, --insane_path** — Path to `Insane4MemPrO.py`. Defaults to the same directory as `MemPrO.py` (or the installed package directory). Only required when using `-bd`.
 
-**-bd, --build_system** — Number of final ranked configurations to build as CG MD-ready systems using Insane4MemPrO. Currently only works with coarse grain input files.
+**-bd, --build_system** — Number of final ranked configurations to build as CG MD-ready systems using Insane4MemPrO. Default is 0 (no systems built). Currently only works with coarse grain input files.
 
 **-bd_args, --build_arguments** — Arguments to pass to Insane4MemPrO, primarily lipid composition, solvent type etc. Required when using `-bd`.
 
@@ -167,10 +175,16 @@ Orient `input_file.pdb` on a grid of 40 starting configurations with 150 minimis
 python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150
 ```
 
-Orient with global curvature minimisation and write per-bead potentials to b-factors:
+Orient with global curvature minimisation:
+
+```
+python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -c
+```
+
+Orient and write per-bead potentials to b-factors (`-wb` is not compatible with `-c`):
 
 ```
-python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -c -wb
+python PATH/TO/MemPrO.py -f input_file.pdb -o Output_dir/ -ng 40 -ni 150 -wb
 ```
 
 Orient with a dual membrane system, then build the top 2 ranked configurations as CG systems. The inner membrane contains POPE, POPG and CARD; the outer membrane contains LIPA:
@@ -255,29 +269,29 @@ MemPrO comes with Insane4MemPrO, a CG system builder based on [Insane](https://g
 
 #### Peptidoglycan layer options
 
-**-pgl** — (Optional) Number of PG layers to place at `-pgl_z`.
+**-pgl** — (Default: 0) Number of PG layers to place at `-pgl_z`.
 
-**-pgl_z** — (Optional) Z position of the PG layer relative to the centre of the periplasmic space.
+**-pgl_z** — (Default: 0) Z position of the PG layer relative to the centre of the periplasmic space.
 
-**-cper** — (Optional) Percentage of cross-links.
+**-cper** — (Default: 0.4) Percentage of cross-links.
 
-**-lper** — (Optional) Percentage of cross-links that are between layers.
+**-lper** — (Default: 0.1) Percentage of cross-links that are between layers.
 
-**-per33** — (Optional) Percentage of 3-3 cross-links; all other cross-links will be 3-4.
+**-per33** — (Default: 0.03) Percentage of 3-3 cross-links; all other cross-links will be 3-4.
 
-**-oper** — (Optional) Percentage chance of a monomer linking with an oligomer. (Actual chance of link is `cper * oper`.)
+**-oper** — (Default: 1) Percentage chance of a monomer linking with an oligomer. (Actual chance of link is `cper * oper`.)
 
 **-gdist** — (Default: 0.75,4,8.9,0.25,10,45) Distribution of glycan strand lengths. Format as `weight1,stddev1,mean1,weight2,...` where each triple describes a Gaussian. The sum of these Gaussians forms the distribution.
 
 #### Protein options
 
-**-fudge** — (Default: 0.3) Fudge factor for allowing lipid-protein overlap.
+**-fudge** — (Default: 0.3) Fudge factor for allowing lipid-protein overlap. A value of 0.15 is recommended when using `-def`.
 
 #### Solvent options
 
 **-sol** — (Required) Solvent type.
 
-**-sold** — (Default: 0.5) Solvent packing density.
+**-sold** — (Default: 0.5) Solvent diameter.
 
 **-solr** — (Default: 0.1) Magnitude of random deviations to solvent positions.
 
@@ -331,7 +345,7 @@ More detailed tutorials are available [here](Insane4MemPrO_tutorials.md).
 
 If your protein hasn't oriented correctly there are a number of things to try:
 
-* Check all orientations by loading `orientations.pdb` and reviewing `orientations.txt`. The correct orientation may not be rank 1.
+* Check all orientations by loading `orientations.pdb` and reviewing `orientation.txt`. The correct orientation may not be rank 1.
 * Check `curv_potential_curve.png` to see if your protein prefers a curved membrane. If so, using `-c` will help.
 * Check the PDB file for missing atoms or residues, which can cause the surface to be incorrectly evaluated. Missing atoms should be fixed before orientation.
 * Using `-wb` can be helpful for diagnosing missing atoms — it writes the potential contribution of each residue as a b-factor, viewable in PyMOL.

{mempro-0.2.1 → mempro-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mempro"
-version = "0.2.1"
+version = "0.3.0"
 description = "Membrane Protein Orientation in Lipid Bilayers"
 readme = "README.md"
 requires-python = ">=3.11"