Installation¶
Instructions¶
Clone the GitHub repository (do not forget to select the appropriate settings to receive notifications of new releases and announcements, and Star the repository to increase its visibility):
git clone git@github.com:pabloprf/MITIM-fusion.git
Hint
It may be useful, at this point, to create a virtual environment to install required MITIM dependencies. For example, using python’s venv package:
python3.12 -m venv mitim-env
source mitim-env/bin/activate
pip install pip --upgrade
Use pip to install all the required MITIM requirements:
pip3 install -e MITIM-fusion[pyqt]
Note
The optional argument [pyqt] added in the intallation command above must only be used if the machine allows for graphic interfaces.
If running in a computing cluster, remove that flag.
The pyqt package is used to create condensed figures into a single notebook when interpreting and plotting simulation results.
If you were unsuccessful in the installation, check out our Frequently Asked Questions section.
User configuration¶
In MITIM-fusion/templates/, there is a config_user_example.json with specifications of where to run certain codes and what the login requirements are.
There are also options to specify the default verbose level and the default DPI for the figures in notebooks.
Users need to specify their own configurations in a file that follows the same structure.
There are different options to handle this config file:
Create a new file named
config_user.jsonin the same folderMITIM-fusion/templates/. MITIM will automatically look for this file when running the code.Create a new file anywhere in your machine. Then, set the environment variable
MITIM_CONFIGto the path of this file. MITIM will automatically look for this file when running the code.Create a new file anywhere in your machine. Then, add these lines at the beginning of your script:
from mitim_tools import config_manager config_manager.set(file_location)
Apart from machine configurations, preferences in config_user.json also includes a verbose_level flag, which indicates the amount of messages that are printed to the terminal when running MITIM:
5: everything (normal prints + information prints + warning prints + questions + optimization progress)
4: information prints + warning prints + questions + optimization progress
3: information prints + warning prints + questions
2: warning prints + questions
1: warning prints
0: nothing
preferences also allows a dpi_notebook value (in percent from standard), which should be adjusted for each user’s screen configuration if the MITIM notebook figures are too small or too large.
This is an example of a config_user.json file that specifies that TGLF should be run in the eofe7.mit.edu machine and TGYRO in the perlmutter.nersc.gov machine.
The slurm options are only required if you are running in a computing cluster that uses the SLURM scheduler, and you can specify the partition, account, nodes to exclude and default memory requirements.
In this example, the identity option is only required if you are running in a computing cluster that requires a specific SSH key to access it.
{
"preferences": {
"tglf": "engaging",
"neo": "local",
"tgyro": "perlmutter",
"verbose_level": "5",
"dpi_notebook": "80"
},
"local": {
"machine": "local",
"username": "YOUR_USERNAME",
"scratch": "/Users/YOUR_USERNAME/scratch/",
"modules": "",
"cores_per_node": 8,
"gpus_per_node": 0
},
"engaging": {
"machine": "eofe7.mit.edu",
"username": "YOUR_USERNAME",
"scratch": "/pool001/YOUR_USERNAME/scratch/",
"modules": "",
"cores_per_node": 64,
"gpus_per_node": 0,
"slurm": {
"partition": "sched_mit_psfc",
"exclusive": false,
"exclude": "node584"
}
},
"perlmutter": {
"machine": "perlmutter.nersc.gov",
"username": "YOUR_USERNAME",
"scratch": "/pscratch/sd/p/YOUR_USERNAME/scratch/",
"modules": "",
"identity": "/Users/YOUR_USERNAME/.ssh/id_rsa_nersc",
"cores_per_node": 32,
"gpus_per_node": 4,
"slurm": {
"account": "YOUR_ACCOUNT",
"partition": "YOUR_PARTITION",
"constraint": "gpu",
"mem": "4GB",
"email": "optional@email"
}
}
}
If you select to run a code in a given machine, please make sure you have ssh rights to that machine with the login instructions specified, unless you are running it locally. MITIM will attempt to create SSH and SFTP connections to that machine, and will ask for the password if it is not available in the SSH keys or via a proxy connection.
Attention
Note that MITIM does not maintain or develop the simulation codes that are used within it, such as those from GACODE or TRANSP. It assumes that proper permissions have been obtained and that working versions of those codes exist in the machine configured to run them.
Please note that MITIM will try to run the codes with standard commands that the shell must understand.
For example, to run the TGLF code, MITIM will want to execute the command tglf in the eofe7.mit.edu machine as specified in the example above.
There are several ways to make sure that the shell understands the command:
1. Send specific commands per code (recommended)
You can populate the modules option per machine in your config_user.json file. For example:
"engaging": {
...
"modules": "export GACODE_ROOT=/home/$USER/gacode && . ${GACODE_ROOT}/shared/bin/gacode_setup"
...
}
Note that you can the same machine listed several times in your config_user.json file, with different modules options per code.
You just need to give it a different name per code.
2. Source at shell initialization
If the commands are available upon login in that machine (e.g. in your personal .bashrc file), MITIM will be able to run them.
Please note that aliases are usually not available in non-interactive shells, and it is recommended to use full paths and to avoid print (echo) statements.
License and contributions¶
MITIM is released under the MIT License, one of the most permissive and widely used open-source software licenses. Our choice of this license aims to make the package as useful and applicable as possible, in support of the development of fusion energy. Embracing the spirit of open-source collaboration, we appreciate users who help increase the visibility of our project by starring the MITIM-fusion GitHub repository and support and acknowledge the continuous development of this tool by citing the following works in any publications, talks and posters:
[1] P. Rodriguez-Fernandez, N.T. Howard, A. Saltzman, S. Kantamneni, J. Candy, C. Holland, M. Balandat, S. Ament and A.E. White, Enhancing predictive capabilities in fusion burning plasmas through surrogate-based optimization in core transport solvers, arXiv:2312.12610 (2023).
[2] P. Rodriguez-Fernandez, N.T. Howard and J. Candy, Nonlinear gyrokinetic predictions of SPARC burning plasma profiles enabled by surrogate modeling, Nucl. Fusion 62, 076036 (2022).
These publications provide foundational insights and methodologies that have significantly contributed to the development of MITIM.
License¶
MIT License
Copyright (c) 2023 Pablo Rodriguez-Fernandez
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.