mempro 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempro
-Version: 0.2.0
+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 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.0 → 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 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.0 → 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", "")
@@ -75,11 +77,27 @@ def _pre_parse_device_args():
 _pre_parse_device_args()
 
 #We need to force JAX to fully utilize a multi-core cpu
-no_cpu = int(os.environ.get("NUM_CPU", os.cpu_count()))
+#By default one device per performance core: each batch of minimisations waits for its slowest device, so on CPUs with
+#efficiency cores (e.g. Apple Silicon, 4P+6E on an M4) using every core is slower (4G1U: 24 s on 10 cores, 16 s on 4)
+def default_device_count():
+	try:
+		import subprocess
+		perf_cores = subprocess.run(["sysctl","-n","hw.perflevel0.physicalcpu"],capture_output=True,text=True,timeout=5)
+		if perf_cores.returncode == 0 and perf_cores.stdout.strip().isdigit():
+			return int(perf_cores.stdout.strip())
+	except (OSError,subprocess.SubprocessError):
+		pass
+	return os.cpu_count()
+no_cpu = int(os.environ.get("NUM_CPU", default_device_count()))
 os.environ["XLA_FLAGS"] = (os.environ.get("XLA_FLAGS", "")+" --xla_force_host_platform_device_count="+str(no_cpu)).strip()
+jax_version = tuple(int(v) for v in jax.__version__.split(".")[:3] if v.isdigit())
 #The legacy (non-thunk) CPU runtime is faster for MemPrO's scan/cond-heavy loops but only exists up to JAX 0.6.0
-if tuple(int(v) for v in jax.__version__.split(".")[:3] if v.isdigit()) <= (0,6,0):
+if jax_version <= (0,6,0):
 	os.environ["XLA_FLAGS"] += " --xla_cpu_use_thunk_runtime=false"
+#XLA's YNNPACK CPU fusions (JAX >= 0.9) intermittently overflow a worker thread's stack on the large vectorised
+#potentials in MemPrO/MemPrOD (SIGBUS in slinky::eval_non_inlined); turning them off costs no measurable speed
+if jax_version >= (0,9,0) and "xla_cpu_experimental_ynn_fusion_type" not in os.environ["XLA_FLAGS"]:
+	os.environ["XLA_FLAGS"] += " --xla_cpu_experimental_ynn_fusion_type="
 
 
 #This is useful for debugging nans in grad
@@ -349,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"
@@ -369,7 +391,7 @@ class PDB_helper:
 			# Collect atom positions
 			atom_pos_list = []
 			atom_bval_list = []
-			atom_nums = []
+			atom_names = []
 
 			for c in atoms:
 				try:
@@ -377,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
 
@@ -391,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}")
@@ -429,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)
@@ -558,36 +567,19 @@ class PDB_helper:
 		total = get_sph_circ(total,jnp.array([0,0]),jnp.pi)
 		total_area = jnp.sum(total)
 		#jax.debug.print("TA{x}",x=total_area)
-		is_surf = jnp.zeros((points.shape[0]))
-		def sloopv3_1(is_surf,ind):
-			pind = ind
-			ang_grid = jnp.zeros((40,20))
-			def sloopv3_2(ang_grid,ind):
-				direc = points[pind]-points[bpoints[pind,ind]]
-				dist = jnp.linalg.norm(direc)
-				def far(ang_grid):
-					return ang_grid
-				def nfar(ang_grid):
-					#angle = (jnp.pi/3)*srad/jnp.max(jnp.array([4.0,dist]))#jnp.arccos(2*dist/srad)#0.6
-					angle = jnp.arccos(jnp.clip(dist/(2*srad),0,1))
-					cen_y = jnp.arctan2(direc[2],jnp.sqrt(direc[0]*direc[0]+direc[1]*direc[1]))
-					cen_x = jnp.arctan2(direc[1],direc[0])
-					ang_grid = get_sph_circ(ang_grid,jnp.array([cen_x,cen_y]),angle)
-					return ang_grid
-				ang_grid = jax.lax.cond((dist < srad*3)*(dist>1e-5),nfar,far,ang_grid)
-				return ang_grid,ind
-			ang_grid,_ = jax.lax.scan(sloopv3_2,ang_grid,jnp.arange(mrad))
-			perc = jnp.sum(ang_grid)/total_area
-			#jax.debug.print("Perc {x}",x=perc)
-			def gthresh(is_surf):
-				is_surf = is_surf.at[ind].set(1)
-				return is_surf
-			def lthresh(is_surf):
-				return is_surf
-			is_surf = jax.lax.cond(perc<thresh,gthresh,lthresh,is_surf)
-			return is_surf,ind
-		is_surf,_=jax.lax.scan(sloopv3_1,is_surf,jnp.arange(points.shape[0]))
-		return is_surf
+		#Each nearby bead (closer than 3*srad) covers a circle of directions; a bead is on the surface if less than
+		#thresh of its directions are covered. get_sph_circ sets cells, so overlapping circles combine as a logical OR
+		def is_surf_fun(pind):
+			direc = points[pind]-points[bpoints[pind]]
+			dist = jnp.linalg.norm(direc,axis=1)
+			angle = jnp.arccos(jnp.clip(dist/(2*srad),0,1))
+			cen_y = jnp.arctan2(direc[:,2],jnp.sqrt(direc[:,0]*direc[:,0]+direc[:,1]*direc[:,1]))
+			cen_x = jnp.arctan2(direc[:,1],direc[:,0])
+			circles = jax.vmap(get_sph_circ,in_axes=(None,0,0))(jnp.zeros((40,20)),jnp.stack((cen_x,cen_y),axis=1),angle)
+			covered = jnp.any((circles > 0)*((dist < srad*3)*(dist>1e-5))[:,None,None],axis=0)
+			perc = jnp.sum(jnp.where(covered,total,0.0))/total_area
+			return jnp.where(perc<thresh,1.0,0.0)
+		return jax.lax.map(is_surf_fun,jnp.arange(points.shape[0]),batch_size=64)
 		
 	#This function gets the surface residues of a given cg protein
 	def get_surface(self):
@@ -602,26 +594,13 @@ class PDB_helper:
 		
 		#Calculating normals at each point of the cg protein
 		timer = time.time()
-		@partial(jax.vmap)
+		#The normal at a bead points away from the mean of all beads within 32 A (beads processed in batches to bound memory)
 		def normal_fun_2(ind):
-			def normal_fun_1(ind_fix,ind):
-				normal_count = jnp.zeros(4)
-				def in_sphere(normal,posa,posb):
-					normal = normal.at[3].set(normal[3]+1)
-					normal = normal.at[:3].set(normal[:3]+(-posa+posb))
-					return normal
-				def not_in_sphere(normal,posa,posb):
-					return normal
-				normal = jax.lax.cond(jnp.linalg.norm(self.poses[ind]-self.poses[ind_fix])<32,in_sphere,not_in_sphere,normal_count,self.poses[ind],self.poses[ind_fix])#8####################<--------------------------
-				return ind_fix,normal
-				
-			_,normals = jax.lax.scan(normal_fun_1,ind,jnp.arange(self.poses.shape[0]))
-			normals_sum = jnp.sum(normals,axis=0)
-			normal = normals_sum[:3]/normals_sum[3]
+			near = jnp.linalg.norm(self.poses-self.poses[ind],axis=1)<32
+			normal = jnp.sum(jnp.where(near[:,None],self.poses[ind]-self.poses,0.0),axis=0)/jnp.sum(near)
 			normal = normal/jnp.linalg.norm(normal)
 			return normal
-		shard_nns = jax.device_put(jnp.arange(self.poses.shape[0]),sharding0)
-		normals = normal_fun_2(shard_nns)
+		normals = jax.lax.map(normal_fun_2,jnp.arange(self.poses.shape[0]),batch_size=256)
 		
 		self.normals = jnp.array(jax.device_get(normals))#jax.device_put(normals)#jax.device_put_sharded([normals],[devices[0]])
 
@@ -646,27 +625,13 @@ class PDB_helper:
 		timer = time.time()
 		#Each point on the surface had an asocciated sphere indicating directions which are exposed
 		#Here we flag the directions which are free
-		@partial(jax.vmap)
+		#A direction is free if no bead lies within 4 A of the point 4 A out along the normal plus that direction
 		def sphere_fun_3(ind):
-			def sphere_fun_2(ind_fix,ind):
-				def sphere_fun_1(ind_fix,ind):
-					def in_prot():
-							return 0
-					def not_in_prot():
-						return 1
-					return ind_fix,jax.lax.cond(jnp.linalg.norm(self.poses[ind_fix[0]]+normals[ind_fix[0]]*4-self.poses[ind]+self.ball[ind_fix[1]])<4,in_prot,not_in_prot)
-				_,on_surf_arr=jax.lax.scan(sphere_fun_1,jnp.array([ind_fix,ind]),jnp.arange(self.poses.shape[0]))
-				on_surf_arr = jnp.array(jax.device_get(on_surf_arr))
-				
-				on_surf = jnp.prod(on_surf_arr)
-				return ind_fix,on_surf
-			_,on_surf_ball = jax.lax.scan(sphere_fun_2,ind,jnp.arange(self.ball.shape[0]))
-			ball_arr = on_surf_ball*self.surface[ind]
-			return ball_arr
-		
-		
-		shard_nn = jax.device_put(jnp.arange(self.poses.shape[0]),sharding0)
-		spheres = sphere_fun_3(shard_nn)
+			test_points = self.poses[ind]+normals[ind]*4+self.ball
+			dists = jnp.linalg.norm(test_points[:,None,:]-self.poses[None,:,:],axis=2)
+			on_surf_ball = jnp.all(jnp.logical_not(dists<4),axis=1).astype(int)
+			return on_surf_ball*self.surface[ind]
+		spheres = jax.lax.map(sphere_fun_3,jnp.arange(self.poses.shape[0]),batch_size=32)
 		
 		self.poses = self.poses[:pos_num]
 		self.surface = self.surface[:pos_num,0]
@@ -680,12 +645,8 @@ class PDB_helper:
 		jax.block_until_ready(self.poses)
 		
 		#Here we set the cartesean directions for each sphere (as before we only had flags)
-		self.spheres = jnp.zeros((surface_number,self.ball.shape[0],3))
-		def set_sphere_poses_fun_2(sphere_poses,ind):
-			timeser = jnp.transpose(jnp.array([surface_sphere[ind],surface_sphere[ind],surface_sphere[ind]]))
-			sphere_poses = sphere_poses.at[ind].set(sphere_poses[ind,:]+timeser*self.ball)
-			return sphere_poses,ind
-		self.spheres,_ = jax.lax.scan(set_sphere_poses_fun_2,self.spheres,jnp.arange(surface_sphere.shape[0]))
+		#surface_number counts the padding rows too (they match surface_poses), and their spheres stay zero
+		self.spheres = jnp.zeros((surface_number,self.ball.shape[0],3)).at[:surface_sphere.shape[0]].set(surface_sphere[:,:,None]*self.ball[None,:,:])
 		surf_mean = jnp.mean(self.surface_poses,axis=0)
 		self.surface_poses = self.surface_poses-surf_mean
 		self.poses = self.poses-surf_mean
@@ -2603,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]
@@ -2626,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):
@@ -3154,13 +3115,28 @@ def read_martini_lines(martini_file):
 	with open(martini_file,"r") as mfile:
 		return tuple(mfile.readlines())
 
-#A fucntion that reads a martini file to get interaction strengths
+#Index of the first line starting with each 12-character "%6s%6s" bead pair, as in [ nonbond_params ]
+@lru_cache(maxsize=None)
+def martini_pair_index(martini_file):
+	index = {}
+	for i,line in enumerate(read_martini_lines(martini_file)):
+		index.setdefault(line[:12],i)
+	return index
+
+#A fucntion that reads a martini file to get interaction strengths (memoised: each pair is looked up once per run)
+#Pairs are found through martini_pair_index (one pass over the file); any pair not found at the start of a line
+#falls back to the original search for the first line containing it
+@lru_cache(maxsize=None)
 def get_int_strength(bead_1,bead_2,martini_file):
 	if(bead_2 == "GHOST"):
 		return 0
 	string = " "*(6-len(bead_1))+bead_1+" "*(6-len(bead_2))+bead_2
 	string2 = " "*(6-len(bead_2))+bead_2+" "*(6-len(bead_1))+bead_1
 	content = read_martini_lines(martini_file)
+	index = martini_pair_index(martini_file)
+	found = [index[s] for s in (string,string2) if s in index]
+	if found:
+		return -float(content[min(found)][32:45])
 	for i,line in enumerate(content):
 		if(string in line or string2 in line):
 			return -float(line[32:45])
@@ -3405,21 +3381,9 @@ def get_sph_circ(grid,cen,angle):
 	dy = jnp.pi/n
 	xs = jnp.linspace(0,2*jnp.pi-dx,2*n)+dx/2
 	ys = jnp.linspace(0,jnp.pi-dy,n)+dy/2
-	def scloop1(grid,ind):
-		ind1 = ind
-		def scloop2(grid,ind):
-			dist = jnp.arccos(jnp.cos(cen[0])*jnp.cos(xs[ind1])+jnp.sin(cen[0])*jnp.sin(xs[ind1])*jnp.cos(cen[1]-ys[ind]))
-			def langle(grid):
-				grid = grid.at[ind1,ind].set(dx*(jnp.cos(ys[ind]-dy/2)-jnp.cos(ys[ind]+dy/2)))
-				return grid
-			def gangle(grid):
-				return grid
-			grid = jax.lax.cond(dist<angle,langle,gangle,grid)
-			return grid,ind
-		grid,_ = jax.lax.scan(scloop2,grid,jnp.arange(n))
-		return grid,ind
-	grid,_ = jax.lax.scan(scloop1,grid,jnp.arange(2*n))
-	return grid
+	dist = jnp.arccos(jnp.cos(cen[0])*jnp.cos(xs)[:,None]+jnp.sin(cen[0])*jnp.sin(xs)[:,None]*jnp.cos(cen[1]-ys)[None,:])
+	cell_area = dx*(jnp.cos(ys-dy/2)-jnp.cos(ys+dy/2))
+	return jnp.where(dist<angle,jnp.broadcast_to(cell_area[None,:],grid.shape),grid)
 	
 def add_Reses(Res, Resitp):
     current_res_no = len(Reses)
@@ -3507,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")
@@ -3537,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")
@@ -3564,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.0 → mempro-0.3.0}/mempro.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mempro
-Version: 0.2.0
+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 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.0 → mempro-0.3.0}/pyproject.toml

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