# Bloch-McConnell (BMC) Simulation Tool
This repository contains a purely python-based Bloch-McConnell (BMC) simulation tool that can be used to simulate
the evolution of the magnetization in various (exchanging) magnetic environments ('pools') under arbitrary
radio-frequency (RF) irradiation. The tool was developed to simulate Chemical Exchange Saturation Transfer (CEST) or
related spectra, but can be used for many other MR simulations as well.
The BMCTool utilizes the [pulseq](https://pulseq.github.io/) open file format to define and store all events (RF pulses,
gradients, delays, ADCs) that shall be simulated. The scanner settings and characteristic properties of the magnetic
environments (relaxation times, pool size fractions, exchange rates) are defined and stored in config-files in the
[YAML](https://yaml.org) file format.
Every simulation requires exactly one seq-file (containing all events) and at least one config-file.
## Installation
The BMCTool can be installed from [PyPi](https://pypi.org/) using
``
pip install bmctool
``
### Initial Test
To make sure that the installation was successful, you can run an example simulation that is provided with both,
the installation using pip and GitHub. To run an example simulation, simply execute the following code:
```python
from bmctool.simulate import sim_example
sim_example()
```
The sim_example function uses the [WASABI.seq](bmctool/library/seq-library/WASABI.seq)
and [config_wasabi.yaml](bmctool/library/sim-library/config_wasabi.yaml) example files. The generated plot should look
like this:
## Starting a Simulation
All simulations using the BMCTool require a config file (in the *yaml* format) that includes all simulation settings
and a sequence file (in the *seq* format), which defines the events to be simulated. An
[example seq-file](bmctool/library/seq-library/WASABI.seq) and an
[example yaml file](bmctool/library/sim-library/config_wasabi.yaml) can be found in the [library](bmctool/library)
subfolder. For more information about config and sequence files and about the
[pulseq-cest-library](library/pulseq-cest-library), where both types of files are shared, please read the
**Pulseq-CEST Library** section below.
If you created your own files or downloaded them from the [pulseq-cest-library](https://github.com/kherz/pulseq-cest-library),
you can start the simulation by running the following code:
```python
from bmctool.simulate import simulate
config_path = '<path_to_your_config>' # can be a str or a Path
seq_path = '<path_to_your_sequence>' # can be a str or a Path
sim = simulate(config_file=config_path, seq_file=seq_path, show_plot=True)
```
The simulate function accepts several additional keyword arguments (**kwargs), that allow to adjust the plot.
These are for example *normalize* (bool: toggle normalization), *norm_threshold* (value/list/array: threshold for
normalization offsets), *offsets* (list/array: manually defined x-values), *invert_ax* (bool: toggle invert ax),
*plot_mtr_asym* (bool:toggle plot MTR_asym) and *title*, *x_label*, *y_label* to control the lables.
The [examples folder](examples) in the [BMCTool GitHub repository](https://github.com/schuenke/BMCTool) contains some
further simulation examples as well as an example script to create your own *WASABI.seq* file. _Please note that this
file will include an additional normalization offset at -300 ppm. To use this for normalization in the simulation,
simply add the kewword argument ``normalize=True`` to the simulate function._
## Pulseq-CEST Project
The BMCTool was developed in parallel to the [pulseq-cest project](https://pulseq-cest.github.io/) that aims to provide
published and approved CEST saturation blocks in the [pulseq](https://pulseq.github.io/) open file format to enable an
exact comparison of CEST saturation blocks with newly developed or adapted saturation blocks for reproducible research.
The [pulseq-cest project](https://pulseq-cest.github.io/) provides a [MATLAB implementation](https://github.com/kherz/pulseq-cest)
and a [python implementation](https://github.com/KerstinHut/pypulseq-cest). The python implementation uses the
[BMCTool](https://github.com/schuenke/BMCTool) and [pypulseq](https://github.com/imr-framework/pypulseq) for config and
seq file handling. Both, the MATLAB and python implementation use the same Bloch-McConnell equation solver implemented
in C++, which is much faster than the solver implemented in the BMCTool itself. For extensive simulations we thus
recommend checking out the [pulseq-cest implementations](https://pulseq-cest.github.io/).
### Pulseq-CEST Library
You will find several pre-defined and approved CEST pre-saturation schemes and simulation configs in the
[pulseq-cest-library GitHub repository](https://github.com/kherz/pulseq-cest-library). You can clone the library using
``
git clone https://github.com/kherz/pulseq-cest-library.git
``
or directly download the latest version as a [ZIP file](https://github.com/kherz/pulseq-cest-library/archive/master.zip).
Raw data
{
"_id": null,
"home_page": "https://github.com/schuenke/BMCTool",
"name": "BMCTool",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "MRI,Bloch,CEST,simulations",
"author": "Patrick Schuenke",
"author_email": "patrick.schuenke@ptb.de",
"download_url": "https://files.pythonhosted.org/packages/fd/25/f24b8fa73c6a12ff40ba0e7c0c631f9bf518092b0bf9e3065304a54c1994/BMCTool-0.6.1.tar.gz",
"platform": null,
"description": "# Bloch-McConnell (BMC) Simulation Tool\r\n\r\nThis repository contains a purely python-based Bloch-McConnell (BMC) simulation tool that can be used to simulate\r\nthe evolution of the magnetization in various (exchanging) magnetic environments ('pools') under arbitrary\r\nradio-frequency (RF) irradiation. The tool was developed to simulate Chemical Exchange Saturation Transfer (CEST) or\r\nrelated spectra, but can be used for many other MR simulations as well.\r\n\r\nThe BMCTool utilizes the [pulseq](https://pulseq.github.io/) open file format to define and store all events (RF pulses,\r\ngradients, delays, ADCs) that shall be simulated. The scanner settings and characteristic properties of the magnetic\r\nenvironments (relaxation times, pool size fractions, exchange rates) are defined and stored in config-files in the\r\n[YAML](https://yaml.org) file format.\r\n\r\nEvery simulation requires exactly one seq-file (containing all events) and at least one config-file.\r\n\r\n## Installation\r\n\r\nThe BMCTool can be installed from [PyPi](https://pypi.org/) using\r\n\r\n``\r\npip install bmctool\r\n``\r\n\r\n### Initial Test\r\n\r\nTo make sure that the installation was successful, you can run an example simulation that is provided with both,\r\nthe installation using pip and GitHub. To run an example simulation, simply execute the following code:\r\n\r\n```python\r\nfrom bmctool.simulate import sim_example\r\nsim_example()\r\n```\r\n\r\nThe sim_example function uses the [WASABI.seq](bmctool/library/seq-library/WASABI.seq)\r\nand [config_wasabi.yaml](bmctool/library/sim-library/config_wasabi.yaml) example files. The generated plot should look\r\nlike this:\r\n\r\n![](https://raw.githubusercontent.com/schuenke/BMCTool/master/examples/example_wasabi_spectrum.png \"Example WASABI spectrum\")\r\n\r\n## Starting a Simulation\r\n\r\nAll simulations using the BMCTool require a config file (in the *yaml* format) that includes all simulation settings\r\nand a sequence file (in the *seq* format), which defines the events to be simulated. An\r\n[example seq-file](bmctool/library/seq-library/WASABI.seq) and an\r\n[example yaml file](bmctool/library/sim-library/config_wasabi.yaml) can be found in the [library](bmctool/library)\r\nsubfolder. For more information about config and sequence files and about the\r\n[pulseq-cest-library](library/pulseq-cest-library), where both types of files are shared, please read the\r\n**Pulseq-CEST Library** section below.\r\n\r\nIf you created your own files or downloaded them from the [pulseq-cest-library](https://github.com/kherz/pulseq-cest-library),\r\nyou can start the simulation by running the following code:\r\n\r\n```python\r\nfrom bmctool.simulate import simulate\r\nconfig_path = '<path_to_your_config>' # can be a str or a Path\r\nseq_path = '<path_to_your_sequence>' # can be a str or a Path\r\nsim = simulate(config_file=config_path, seq_file=seq_path, show_plot=True)\r\n```\r\n\r\nThe simulate function accepts several additional keyword arguments (**kwargs), that allow to adjust the plot.\r\nThese are for example *normalize* (bool: toggle normalization), *norm_threshold* (value/list/array: threshold for\r\nnormalization offsets), *offsets* (list/array: manually defined x-values), *invert_ax* (bool: toggle invert ax),\r\n*plot_mtr_asym* (bool:toggle plot MTR_asym) and *title*, *x_label*, *y_label* to control the lables.\r\n\r\nThe [examples folder](examples) in the [BMCTool GitHub repository](https://github.com/schuenke/BMCTool) contains some\r\nfurther simulation examples as well as an example script to create your own *WASABI.seq* file. _Please note that this\r\nfile will include an additional normalization offset at -300 ppm. To use this for normalization in the simulation,\r\nsimply add the kewword argument ``normalize=True`` to the simulate function._\r\n\r\n## Pulseq-CEST Project\r\n\r\nThe BMCTool was developed in parallel to the [pulseq-cest project](https://pulseq-cest.github.io/) that aims to provide\r\npublished and approved CEST saturation blocks in the [pulseq](https://pulseq.github.io/) open file format to enable an\r\nexact comparison of CEST saturation blocks with newly developed or adapted saturation blocks for reproducible research.\r\nThe [pulseq-cest project](https://pulseq-cest.github.io/) provides a [MATLAB implementation](https://github.com/kherz/pulseq-cest)\r\nand a [python implementation](https://github.com/KerstinHut/pypulseq-cest). The python implementation uses the\r\n[BMCTool](https://github.com/schuenke/BMCTool) and [pypulseq](https://github.com/imr-framework/pypulseq) for config and\r\nseq file handling. Both, the MATLAB and python implementation use the same Bloch-McConnell equation solver implemented\r\nin C++, which is much faster than the solver implemented in the BMCTool itself. For extensive simulations we thus\r\nrecommend checking out the [pulseq-cest implementations](https://pulseq-cest.github.io/).\r\n\r\n### Pulseq-CEST Library\r\n\r\nYou will find several pre-defined and approved CEST pre-saturation schemes and simulation configs in the\r\n[pulseq-cest-library GitHub repository](https://github.com/kherz/pulseq-cest-library). You can clone the library using\r\n\r\n``\r\ngit clone https://github.com/kherz/pulseq-cest-library.git\r\n``\r\n\r\nor directly download the latest version as a [ZIP file](https://github.com/kherz/pulseq-cest-library/archive/master.zip).\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A python tool to perform Bloch-McConnell (BMC) simulations.",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://github.com/schuenke/BMCTool"
},
"split_keywords": [
"mri",
"bloch",
"cest",
"simulations"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb37d156e0899f5d98e35bee5a8826b03f248742de2bcf9b314d043107d8dbde",
"md5": "d91f7b9f9364ea57b62724526d77d808",
"sha256": "799058f9e5aeefe006976b2c2c24fa46d988f83f16fc931cf703aa54cbd216d4"
},
"downloads": -1,
"filename": "BMCTool-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d91f7b9f9364ea57b62724526d77d808",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 31544,
"upload_time": "2023-07-03T13:50:27",
"upload_time_iso_8601": "2023-07-03T13:50:27.652646Z",
"url": "https://files.pythonhosted.org/packages/eb/37/d156e0899f5d98e35bee5a8826b03f248742de2bcf9b314d043107d8dbde/BMCTool-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd25f24b8fa73c6a12ff40ba0e7c0c631f9bf518092b0bf9e3065304a54c1994",
"md5": "160efb458fbe54ae6e1fa6f4a7cbf235",
"sha256": "82dfa7f1b35a337305926544131e1c63a278ce10700ff2714e712f39f988d446"
},
"downloads": -1,
"filename": "BMCTool-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "160efb458fbe54ae6e1fa6f4a7cbf235",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 25725,
"upload_time": "2023-07-03T13:50:29",
"upload_time_iso_8601": "2023-07-03T13:50:29.480384Z",
"url": "https://files.pythonhosted.org/packages/fd/25/f24b8fa73c6a12ff40ba0e7c0c631f9bf518092b0bf9e3065304a54c1994/BMCTool-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-03 13:50:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "schuenke",
"github_project": "BMCTool",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bmctool"
}
JSON
