From 3afdd21f7863dd80cab85e60c53b2385388afea1 Mon Sep 17 00:00:00 2001 From: Ethan Shanahan Date: Mon, 30 Mar 2026 15:53:22 +0200 Subject: [PATCH] MSData info and assorted tweaks --- docs/index.md | 12 +++++----- .../adding-microstructure-data.md | 24 +++++++++++-------- docs/introduction/analysing-results.md | 8 +++---- docs/introduction/getting-started.md | 2 +- docs/introduction/installing-the-plugin.md | 2 +- docs/introduction/running-fans.md | 9 ++++--- docs/reference/plugin-api.md | 2 +- docs/tutorial/installing-the-tutorial.md | 4 ++-- 8 files changed, 33 insertions(+), 30 deletions(-) diff --git a/docs/index.md b/docs/index.md index 1a5260b..7db8c85 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,25 +5,25 @@ [![License][license-badge]][license-link] [![Docs Status][docs-badge]][docs-link] -!!! abstract "Supports FANS v0.6.0" +!!! abstract "Supports FANS v0.6.2" An [AiiDA](https://www.aiida.net/) plugin to integrate with [FANS](https://github.com/DataAnalyticsEngineering/FANS). Use the Fourier-Accelerated Nodal Solver (FANS) to calculate microscale multiphysics problems with the automated data tracking of AiiDA. FANS is an efficient, parallelised, FFT-based homogenisation solver, making AiiDA ideal to manage its very high throughput capabilities. The AiiDA-FANS plugin is an open-source project developed at the Institute of Applied Mechanics, Univeristy of Stuttgart, in association with the developers of FANS. ## How to Cite -The writing of a research paper regarding the AiiDA-FANS plugin is underway. Until the time that it is published, please consider if it may be relevant to instead cite one of the following papers. +For now, please consider citing one of the following papers if -=== "AiiDA" +=== "FANS" !!! quote "" - Sebastiaan. P. Huber, Spyros Zoupanos, Martin Uhrin, Leopold Talirz, Leonid Kahle, Rico Häuselmann, Dominik Gresch, Tiziano Müller, Aliaksandr V. Yakutovich, Casper W. Andersen, Francisco F. Ramirez, Carl S. Adorf, Fernando Gargiulo, Snehal Kumbhar, Elsa Passaro, Conrad Johnston, Andrius Merkys, Andrea Cepellotti, Nicolas Mounet, Nicola Marzari, Boris Kozinsky, and Giovanni Pizzi, AiiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance, Scientific Data 7, 300 (2020); DOI: 10.1038/s41597-020-00638-4 + Leuschner, M., Fritzen, F. Fourier-Accelerated Nodal Solvers (FANS) for homogenization problems. Comput Mech 62, 359–392 (2018). https://doi.org/10.1007/s00466-017-1501-5 -=== "FANS" +=== "AiiDA" !!! quote "" - Leuschner, M., Fritzen, F. Fourier-Accelerated Nodal Solvers (FANS) for homogenization problems. Comput Mech 62, 359–392 (2018). https://doi.org/10.1007/s00466-017-1501-5 + Sebastiaan. P. Huber, Spyros Zoupanos, Martin Uhrin, Leopold Talirz, Leonid Kahle, Rico Häuselmann, Dominik Gresch, Tiziano Müller, Aliaksandr V. Yakutovich, Casper W. Andersen, Francisco F. Ramirez, Carl S. Adorf, Fernando Gargiulo, Snehal Kumbhar, Elsa Passaro, Conrad Johnston, Andrius Merkys, Andrea Cepellotti, Nicolas Mounet, Nicola Marzari, Boris Kozinsky, and Giovanni Pizzi, AiiDA 1.0, a scalable computational infrastructure for automated reproducible workflows and data provenance, Scientific Data 7, 300 (2020); DOI: 10.1038/s41597-020-00638-4 [release-badge]: https://img.shields.io/github/v/release/dataanalyticsengineering/AiiDA-FANS?label=Release diff --git a/docs/introduction/adding-microstructure-data.md b/docs/introduction/adding-microstructure-data.md index 654fb43..fd6e48f 100644 --- a/docs/introduction/adding-microstructure-data.md +++ b/docs/introduction/adding-microstructure-data.md @@ -8,26 +8,30 @@ wget https://github.com/DataAnalyticsEngineering/AiiDA-FANS/raw/refs/heads/main/ Alternatively, you can visit the [FANS repository](https://github.com/DataAnalyticsEngineering/FANS) for more information and sample microstructures. -Since realistic microstructure files tend to be extremely big, saving such files in an AiiDA profile has some significant drawbacks. As such, you are required to put the microstructure file on the same machine as where you intend to run FANS. We recommend you locate it in the working directory of the AiiDA computer you created, within a subdirectory called "microstructures/". +Since realistic microstructure files tend to be extremely large, saving such files in an AiiDA profile has some significant drawbacks. As such, we strongly recommend you put the microstructure file on the same machine as where you intend to run FANS. You may place it inside the working directory of the AiiDA computer you created, within a subdirectory called "microstructures/". -Once you have a microstructure file, you must create a `RemoteData` node like so: +Once you have a microstructure file, you must create a `MicrostructureData` node like so: ```python from aiida import load_profile -from aiida.orm import RemoteData, load_computer +from aiida.orm import load_computer +from aiida.plugins import DataFactory load_profile() -COMPUTER_LABEL = "localhost" MICROSTRUCTURE_PATH = "/path/to/microstructures/ms-example.h5" +DATASET_NAME = "/dset_0/image" +COMPUTER_LABEL = "localhost" -RemoteData( - remote_path=MICROSTRUCTURE_PATH, - computer=load_computer(COMPUTER_LABEL), - label="microstructure.file", +MicrostructureData = DataFactory("fans.microstructure") +MicrostructureData( + MICROSTRUCTURE_PATH, + DATASET_NAME, + computer=load_computer(label=COMPUTER_LABEL), + label="microstructure.data" ).store() ``` -You can write this in a python script and run it, or use AiiDA's interactive shell with `verdi shell`. If you use the interactive shell, you can omit `load_profile` as AiiDA will automatically load the default profile. Remember to change `COMPUTER_LABEL` and `MICROSTRUCTURE_PATH` to the appropriate values. After storing the node, you can check the nodes on your profile with `verdi node list` and expose details of a particular node with `verdi node show `. +You can write this in a python script and run it, or use AiiDA's interactive shell with `verdi shell`. If you use the interactive shell, you can omit `load_profile` and `import DataFactory` as AiiDA will automatically loads the default profile and imports some useful tools. Remember to change `MICROSTRUCTURE_PATH`, `DATASET_NAME`, and `COMPUTER_LABEL` to their appropriate values. After storing the node, you can check the nodes on your profile with `verdi node list` and expose details of a particular node with `verdi node show `. -To reuse this node when executing `FansCalculation` jobs, you can use `load_node(label="microstructure.file")` as long as only one node exists with the provided label. If you intend on using multiple microstructure files, assign them identifiable labels. +To reuse this node when executing `FansCalculation` jobs, you can use `load_node(label="microstructure.data")` as long as only one node exists with the provided label. If you intend on using multiple files and/or multiple groups within individual files, assign each node a distinct and identifiable label. diff --git a/docs/introduction/analysing-results.md b/docs/introduction/analysing-results.md index 2963375..169f373 100644 --- a/docs/introduction/analysing-results.md +++ b/docs/introduction/analysing-results.md @@ -9,7 +9,7 @@ verdi node list --project id label node_type Once you have run at least one simulation, you will notice a `CalcJobNode`, labelled "FANS" by default. This represents the execution of a FANS process. You may want to visualise a portion of the graph connected to this node. ```sh -verdi node graph generate +verdi node graph generate --identifier label ``` The pdf this creates arranges the input nodes on top, the calculation node in the middle, and the output nodes below. @@ -20,7 +20,7 @@ To quickly interact with a specific nodes, you can enter the `verdi shell`. This ### 1. `RemoteData` -This node refers to the specific working directory of the process. It is a subdirectory of the working directory you provided when specifying the computer. It is capable of establishing a connection to remote machine to provide access to the original data. For example, you can use this connection to list the objects within the assigned directory. +This node refers to the specific working directory of the process. It is a subdirectory of the working directory you provided when specifying the computer. It is capable of establishing a connection to remote machine to provide access to the original data. For example, you can use this connection to list the objects within the assigned directory: ```python remote_data.get_remote_path() @@ -29,7 +29,7 @@ remote_data.listdir() ### 2. `FolderData` -Similar to the `RemoteData`, this node represents a directory-like object, but unlike the `RemoteData`, this node stores the contents of the directory in the AiiDA repository. With this type of node, you can navigate the directory, add or remove files and folders, and get the contents of files. The plugin stores a FolderData node containing the standard output and standard error files of FANS and the AiiDA scheduler. This is how you can print the standard output of FANS. +Similar to the `RemoteData`, this node represents a directory-like object, but unlike the `RemoteData`, this node stores the contents of the directory in the AiiDA repository. With this type of node, you can navigate the directory, add or remove files and folders, and get the contents of files. The plugin stores a FolderData node containing the standard output and standard error files of FANS and the AiiDA scheduler. This is how you can print the standard output of FANS: ```python folder_data.list_object_names() @@ -38,7 +38,7 @@ print(folder_data.get_object_content("FANS.log")) ### 3. `SinglefileData` -The `SinglefileData` node is much like the `FolderData` node, but, as the name suggests, is for a single file rather than a whole directory. The plugin saves the resulting output hdf5 file from FANS as a `SinglefileData` node. The following is similar to how the plugin's parser extracts the results. +The `SinglefileData` node is much like the `FolderData` node, but, as the name suggests, is for a single file rather than a whole directory. The plugin saves the resulting output hdf5 file from FANS as a `SinglefileData` node. The following code snippet is similar to how the plugin's parser extracts the results: ```python singlefile_data.filename() diff --git a/docs/introduction/getting-started.md b/docs/introduction/getting-started.md index bb8e256..c40fcba 100644 --- a/docs/introduction/getting-started.md +++ b/docs/introduction/getting-started.md @@ -11,4 +11,4 @@ To use AiiDA-FANS, you need to take the following first steps. AiiDA often undergoes significant changes, so for details on how to accomplish many of these steps you should refer to the [AiiDA docs](https://aiida.readthedocs.io/projects/aiida-core/en/stable/) for the latest information or the accompanying [tutorial](../tutorial/installing-the-tutorial.md) for details on a specific version of AiiDA that is likely still relevant. -FANS is a simple program to install via conda-forge. You can find out more about it, including alternative installation methods, on the [FANS repository](https://github.com/DataAnalyticsEngineering/FANS). You should consider installing FANS on a HPC to get the fullest out of its capabilities, and allowing AiiDA to [access it via ssh](https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/ssh.html). +FANS is straightforward to install via conda-forge. You can find out more about it, including alternative installation methods, on the [FANS repository](https://github.com/DataAnalyticsEngineering/FANS). You should consider installing FANS on a HPC, and allowing AiiDA to [access it via ssh](https://aiida.readthedocs.io/projects/aiida-core/en/stable/howto/ssh.html), to get the most out of its capabilities. diff --git a/docs/introduction/installing-the-plugin.md b/docs/introduction/installing-the-plugin.md index ae83af1..145392d 100644 --- a/docs/introduction/installing-the-plugin.md +++ b/docs/introduction/installing-the-plugin.md @@ -3,4 +3,4 @@ You will need to install the plugin before you can create the code node on your AiiDA profile. AiiDA-FANS is available on the conda-forge package channel. Our recommended method of installing AiiDA-FANS is to use the [Pixi](https://pixi.sh/latest/) package manager, in which case `pixi add aiida-fans` will add the plugin to your project manifest (i.e. a pyproject.toml or pixi.toml file). This way, the plugin and its dependencies (aiida-core and h5py) will be installed in an isolated environment. !!! note - Even if you install AiiDA in an isolated environment, it will by default continue to use your home directory to manage profiles, thus sharing the same space as any other installation of AiiDA you may have on your system. + Even if you install AiiDA in an isolated environment, it will, by default, continue to use your home directory to manage profiles, thus sharing the same space as any other installation of AiiDA you may have on your system. diff --git a/docs/introduction/running-fans.md b/docs/introduction/running-fans.md index 4da6a68..1d783b9 100644 --- a/docs/introduction/running-fans.md +++ b/docs/introduction/running-fans.md @@ -21,11 +21,11 @@ QueryBuilder() .all(flat=True) ``` -but there are dangers herein since if another input parameter happens to have the same value, they would both be fetched. To get around this, you would need to have the foresight to label each node appropriately. Additionally, different data types have different query interfaces, making the overall user experience a challenge. +but there are dangers herein since if another input parameter happens to have the same value, they would both be fetched. To get around this, you would need to have the foresight to label each node appropriately. Additionally, different data types have different query interfaces, making the overall user experience a challenging one. ## Using Utilities Instead -In comes the `utils.execute_fans` function. With this function, you can provide the input parameters of FANS as basic pythonic values in a dictionary (with some nuances). Here is what a script to run FANS might look like, +Introducing the `utils.execute_fans` function. With this function, you can provide the input parameters of FANS as basic pythonic values in a dictionary (with some nuances). Here is what a script to run FANS might look like, ```python from aiida import load_profile @@ -40,8 +40,7 @@ inputs = { "code": load_code("FANS"), # Code node goes here. # Microstructure definition "microstructure": { - "file": load_node(label="microstructure.file"), # MS node goes here. - "datasetname": "/dset_0/image", + "data": load_node(label="microstructure.data"), # MS node goes here. "L": [1.0, 1.0, 1.0], }, # Problem type and material model @@ -70,6 +69,6 @@ inputs = { run_fans(inputs=inputs) ``` -Note that the `inputs` dictionary closely resembles the input json required by FANS, with two exceptions. These are: the addition of the `"code": load_code("FANS")` entry which is an additional requirement of running any AiiDA `CalcJob`, and the `"microstructure": {"filepath": "path/to/ms.h5", ...` entry which has changed to `"microstructure": {"file": load_node(label="microstructure.file"), ...` according to the section on [Adding Microstructure Data](adding-microstructure-data.md). The final function call to `run_fans` is analogous to the AiiDA `run` function, and there exists a corresponding `submit_fans` function too. +Note that the `inputs` dictionary closely resembles the input json required by FANS, with two exceptions. These are: the addition of the `"code": load_code("FANS")` entry which is an additional requirement of running any AiiDA `CalcJob`, and the `"microstructure": {"filepath": "path/to/ms.h5", "datasetname": "/path/to/group", ...` entry which has changed to `"microstructure": {"data": load_node(label="microstructure.data"), ...` according to the section on [Adding Microstructure Data](adding-microstructure-data.md). The final function call to `run_fans` is analogous to the AiiDA `run` function, and there exists a corresponding `submit_fans` function too. The utilities function will first check each non-node entry in the dictionary and try to find an existing node whose value matches that which was provided and whose label matches the dictionary key of that input (using dot notation for embedded dictionaries). Additionally, if there exists a calculation whose inputs perfectly match the inputs provided, confirmation to proceed will be sought. diff --git a/docs/reference/plugin-api.md b/docs/reference/plugin-api.md index fc85b7e..5fea301 100644 --- a/docs/reference/plugin-api.md +++ b/docs/reference/plugin-api.md @@ -13,4 +13,4 @@ ### Error Codes - +## MicrostructureData diff --git a/docs/tutorial/installing-the-tutorial.md b/docs/tutorial/installing-the-tutorial.md index 3b4f119..3c26afd 100644 --- a/docs/tutorial/installing-the-tutorial.md +++ b/docs/tutorial/installing-the-tutorial.md @@ -1,9 +1,9 @@ # Installing the Tutorial -A tutorial accompanies this plugin. To try it out: clone the [source repository][source-link], cd into it, run `pixi shell -e tutorial` and `pixi run tutorial`. The marimo notebook should be served locally. - !!! info More information coming soon. +A tutorial accompanies this plugin. To try it out: clone the [source repository][source-link], cd into it, run `pixi shell -e tutorial` and `pixi run tutorial`. The marimo notebook should be served locally. + [source-link]: https://github.com/DataAnalyticsEngineering/AiiDA-FANS