pyvale 2025.7.2__cp311-cp311-win_amd64.whl → 2025.8.1__cp311-cp311-win_amd64.whl

pyvale/examples/mooseherder/ex4_run_gmsh-moose_seq_para.py

@@ -0,0 +1,176 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Running a parameter sweep of a Gmsh and MOOSE simulation
+================================================================================
+
+In this example we will perform a parameter sweep of a gmsh-moose simulation
+chain to demonstrate the capability of the 'herder' workflow manager. Here we
+pass the 'herder' a list of simulation tools that we want to modify inputs for
+(i.e. input modifiers) and then run (i.e. with runners). The simulation tools
+are called sequentially in the order they are in the lists so we will need to
+make sure we call gmsh first to generate the mesh and then call moose to use the
+mesh to run the simulation.
+
+As in the previous example we will generate a parameter sweep and then run it
+sequentially and in parallel and compare the run times.
+
+**Installing moose**: To run this example you will need to have installed moose
+on your system. As moose supports unix operating systems windows users will need
+to use windows subsystem for linux (WSL). We use the proteus moose build which
+can be found here: https://github.com/aurora-multiphysics/proteus. Build scripts
+for common linux distributions can be found in the 'scripts' directory of the
+repo. You can also create your own moose build using instructions here:
+https://mooseframework.inl.gov/.
+
+**Installing gmsh**: For this example you will need to have a gmsh executable
+which can be downloaded and installed from here: https://gmsh.info/#Download
+
+We start by importing what we need for this example.
+"""
+
+from pathlib import Path
+import numpy as np
+
+#pyvale imports
+import pyvale.dataset as dataset
+from pyvale.mooseherder import (MooseHerd,
+                                MooseRunner,
+                                MooseConfig,
+                                GmshRunner,
+                                InputModifier,
+                                DirectoryManager,
+                                sweep_param_grid)
+
+#%%
+# First we setup our input modifer and runner for gmsh using the same 2D plate
+# with a hole simulation test case from the pyvale simulation library. This is
+# the same as we have seen in previous examples for the gmsh input modifier and
+# running gmsh.
+sim_case: int = 17
+
+gmsh_input = dataset.sim_case_gmsh_file_path(case_num=sim_case)
+gmsh_modifier = InputModifier(gmsh_input,"//",";")
+
+gmsh_path = Path.home() / "gmsh/bin/gmsh"
+gmsh_runner = GmshRunner(gmsh_path)
+gmsh_runner.set_input_file(gmsh_input)
+
+
+#%%
+# Next we setup our moose input modifier and runner in the same way as we have
+# done in previous examples. We set our parallelisation options for moose here
+# as well as redirecting stdout to file to save our terminal when we run in
+# parallel.
+moose_input = dataset.sim_case_input_file_path(case_num=sim_case)
+moose_modifier = InputModifier(moose_input,"#","")
+
+config = {'main_path': Path.home()/ 'moose',
+          'app_path': Path.home() / 'proteus',
+          'app_name': 'proteus-opt'}
+moose_config = MooseConfig(config)
+moose_runner = MooseRunner(moose_config)
+moose_runner.set_run_opts(n_tasks = 1,
+                          n_threads = 2,
+                          redirect_out = True)
+
+#%%
+# We can now setup our 'herd' workflow manager making sure me place gmsh ahead
+# of moose in the input modifier and runner lists so it is executed first to
+# generate our mesh. We setup our directories and number of simulations to run
+# in paralle as we have done previously.
+num_para_sims: int = 4
+
+sim_runners = [gmsh_runner,moose_runner]
+input_modifiers = [gmsh_modifier,moose_modifier]
+dir_manager = DirectoryManager(n_dirs=num_para_sims)
+
+herd = MooseHerd(sim_runners,input_modifiers,dir_manager)
+herd.set_num_para_sims(n_para=num_para_sims)
+
+
+#%%
+# We need somewhere to run our simulations and store the output so we create our
+# standard pyvale output directory and then we set this as the base directory
+# for our directory manager. We clear any old output directories and then create
+# new ones ready to write our simulation output to.
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+dir_manager.set_base_dir(output_path)
+dir_manager.clear_dirs()
+dir_manager.create_dirs()
+
+#%%
+# We can now setup our grid parameter sweep to run simulations for all
+# combinations of variables we are interested in. For now we will only change
+# the parameters of our gmsh simulation so we set our moose parameters to None.
+# For the gmsh simulation parameters we pass a dictionary keyed by the variable
+# we want to change and then an iterable object (e.g. tuple, list, numpy array)
+# for all values of the variable we want to run. We can also have an iterable of
+# strings which will insert expressions into the input file for us as shown for
+# the plate height below. If we only want to analyse a single value of a
+# parameter we just pass an iterable with a single element. Note that the list
+# of parameters that we pass to the sweep grid function should be in the same
+# order we intend to call our simulation tools - so gmsh first in this case.
+#
+# After running this example replace the moose params with the following:
+# ``moose_params = {"EMod": (70e9,100e9),"PRatio": (0.3,0.35)}``. This should
+# demonstrate how all combinations of parameters between both gmsh and moose are
+# generated using the sweep grid function.
+gmsh_params = {"plate_width": np.array([150e-3,100e-3]),
+               "plate_height": ("plate_width + 100e-3",
+                                "plate_width + 50e-3")}
+moose_params = None
+params = [gmsh_params,moose_params]
+sweep_params = sweep_param_grid(params)
+
+print("\nParameter sweep variables by simulation:")
+for ii,pp in enumerate(sweep_params):
+    print(f"Sim: {ii}, Params [gmsh,moose]: {pp}")
+
+#%%
+# The run once function of the herd allows us to run a particular single
+# simulation chain from anywhere in the sweep. This is useful for debugging when
+# you want to rerun a single case to see the output or what went wrong. The herd
+# also stores the solution time for each single iteration so we will store this
+# to estimate how long the whole sweep should take when solving sequentially.
+herd.run_once(0,sweep_params[0])
+time_run_once = herd.get_iter_time()
+
+
+#%%
+# We can run the whole parameter sweep sequentially (one by one) using the run
+# sequential function of the herd. We also store the total solution time
+# for all simulation chains so that we can compare to a parallel run later. Note
+# that it can be beneficial to run sequentially if you are using the herd within
+# another loop or if one of the steps in your simulation chain is expensive and
+# that step needs the computational resource.
+herd.run_sequential(sweep_params)
+time_run_seq = herd.get_sweep_time()
+
+#%%
+# Finally, we can run our parameter sweep in parallel. We need a main guard here
+# as we use the multi-processing package. We also store the sweep time for this
+# case to compare our sequential to parallel run time.
+if __name__ == "__main__":
+    herd.run_para(sweep_params)
+    time_run_para = herd.get_sweep_time()
+
+#%%
+# Now that we have run all cases we can compare run times for a single
+# simulation multiplied by the total number of simulations against runnning the
+# sweep in parallel
+print("-"*80)
+print(f'Run time (one iter)             = {time_run_once:.3f} seconds')
+print(f'Est. time (one iter x num sims) = {(time_run_once*len(sweep_params)):.3f} seconds')
+print()
+print(f'Run time (seq)      = {time_run_seq:.3f} seconds')
+print(f'Run time (para)     = {time_run_para:.3f} seconds')
+print("-"*80)
+print()

pyvale/examples/mooseherder/ex5_run_moose_paramulti.py

@@ -0,0 +1,136 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Using multiple calls to run parallel sweeps
+================================================================================
+
+In this example we demonstrate how multiple repeated calls can be made to run
+'herd' workflow manager where the simulations do not overwrite each other,
+instead they accumulate within the output directories. If you need the
+simulation output to be cleared after each call to run a sweep sequentially or
+in parallel then you will need to call clear using the directory manager.
+
+**Installing moose**: To run this example you will need to have installed moose
+on your system. As moose supports unix operating systems windows users will need
+to use windows subsystem for linux (WSL). We use the proteus moose build which
+can be found here: https://github.com/aurora-multiphysics/proteus. Build scripts
+for common linux distributions can be found in the 'scripts' directory of the
+repo. You can also create your own moose build using instructions here:
+https://mooseframework.inl.gov/.
+
+We start by importing what we need for this example. For this example the
+everything at the start is similar to previous examples where we have setup
+our herd workflow manager. So, if you feel confident with things so far then
+skip down to the last section.
+"""
+
+from pathlib import Path
+import numpy as np
+
+#pyvale imports
+import pyvale.dataset as dataset
+from pyvale.mooseherder import (MooseHerd,
+                                MooseRunner,
+                                MooseConfig,
+                                InputModifier,
+                                DirectoryManager,
+                                sweep_param_grid)
+
+#%%
+# First we setup an input modifier and runner for our moose simulation in
+# exactly the same way as we have done in previous examples.
+
+moose_input = dataset.element_case_input_path(dataset.EElemTest.HEX20)
+moose_modifier = InputModifier(moose_input,'#','')
+
+config = {'main_path': Path.home()/ 'moose',
+        'app_path': Path.home() / 'proteus',
+        'app_name': 'proteus-opt'}
+moose_config = MooseConfig(config)
+
+moose_runner = MooseRunner(moose_config)
+moose_runner.set_run_opts(n_tasks = 1,
+                          n_threads = 2,
+                          redirect_out = True)
+
+#%%
+# We use the moose input modifier and runner to create our herd workflow manager
+# as we have seen in previous examples.
+num_para_sims: int = 4
+dir_manager = DirectoryManager(n_dirs=num_para_sims)
+herd = MooseHerd([moose_runner],[moose_modifier],dir_manager)
+herd.set_num_para_sims(n_para=num_para_sims)
+
+#%%
+# We need somewhere to run our simulations and store the output so we create our
+# standard pyvale output directory as we have done in previous examples and then
+# pass this to our directory manager.
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+dir_manager.set_base_dir(output_path)
+dir_manager.reset_dirs()
+
+#%%
+# We generate a grid sweep of the variables we are interested in analysing as
+# we have done previously and then print this to the console so we can check
+# all combinations of variables that we want are present and that the total
+# number of simulations makes sense.
+
+moose_params = {"nElemX": (2,3),
+                "lengX": np.array([10e-3,15e-3]),
+                "PRatio":(0.3,)}
+params = [moose_params,]
+sweep_params = sweep_param_grid(params)
+
+print("\nParameter sweep variables by simulation:")
+for ii,pp in enumerate(sweep_params):
+    print(f"Sim: {ii}, Params [moose,]: {pp}")
+
+print()
+print(f"Total simulations = {len(sweep_params)}")
+print()
+
+#%%
+# Here we are going to run the parameter sweep a certain number of times and
+# while storing the total time to complete the parameter sweep each time. Once
+# we have completed all the parameter sweeps we print the time taken for each
+# sweep and the average sweep time to the console.
+#
+# Now if we inspect the simulation working directories in our pyvale-output
+# directory we will see that all runs have been stored. If we need to clear
+# the directories in between parallel sweeps we can call
+# ``dir_manager.reset_dirs()`` and then we will only be left with one copy of
+# the sweep output. Retaining all simulations is useful if we want to update
+# the parameters we are passing to the ``run_para`` function every time it
+# is called.
+
+num_para_runs: int = 3
+
+if __name__ == '__main__':
+    sweep_times = np.zeros((num_para_runs,),dtype=np.float64)
+    for rr in range(num_para_runs):
+        herd.run_para(sweep_params)
+        sweep_times[rr] = herd.get_sweep_time()
+
+
+print(80*"-")
+for ii,ss in enumerate(sweep_times):
+    print(f"Sweep {ii} took: {ss:.3f}seconds")
+
+print(80*"-")
+print(f"Average sweep time: {np.mean(sweep_times):.3f} seconds")
+print(80*"-")
+
+
+
+
+
+
+
+

pyvale/examples/mooseherder/ex6_read_moose_exodus.py

@@ -0,0 +1,163 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Reading exodus output from a MOOSE simulation
+================================================================================
+
+In this example we ...
+
+**Installing moose**: To run this example you will need to have installed moose
+on your system. As moose supports unix operating systems windows users will need
+to use windows subsystem for linux (WSL). We use the proteus moose build which
+can be found here: https://github.com/aurora-multiphysics/proteus. Build scripts
+for common linux distributions can be found in the "scripts" directory of the
+repo. You can also create your own moose build using instructions here:
+https://mooseframework.inl.gov/.
+
+We start by importing what we need for this example.
+"""
+
+import time
+import shutil
+from pathlib import Path
+from typing import Any
+import dataclasses
+import numpy as np
+
+#pyvale imports
+import pyvale.dataset as dataset
+import pyvale.sensorsim as sens
+from pyvale.mooseherder import (MooseRunner,
+                                MooseConfig,
+                                ExodusReader)
+
+#%%
+# We also define a helper function that will print all attriubutes of a
+# dataclas so we can see what it contains. This will be useful when we inspect
+# what our ``SimData`` objects contain.
+def print_attrs(in_obj: Any) -> None:
+    for field in dataclasses.fields(in_obj):
+        if not field.name.startswith('__'):
+            print(f"    {field.name}: {field.type}")
+
+#%%
+# We need to know where our simulation output is so we are going to create our
+# standard pyvale-output directory, grab our simulation input file from the
+# pyvale simulation library and then copy it to this directory to run. This
+# means the output exodus will appear in the same directory as the input file.
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+moose_file = dataset.element_case_input_path(dataset.EElemTest.HEX20)
+moose_input = output_path / moose_file.name
+
+shutil.copyfile(moose_file,moose_input)
+
+
+#%%
+# We now create our moose runner with the same method we have used in previous
+# examples. We run the simulation and time it, printing the solve time to the
+# terminal.
+
+config = {"main_path": Path.home()/ "moose",
+          "app_path": Path.home() / "proteus",
+          "app_name": "proteus-opt"}
+moose_config = MooseConfig(config)
+
+moose_runner = MooseRunner(moose_config)
+
+moose_runner.set_run_opts(n_tasks=1, n_threads=4, redirect_out=True)
+
+moose_runner.set_input_file(moose_input)
+
+start_time = time.perf_counter()
+moose_runner.run()
+run_time = time.perf_counter() - start_time
+
+print("-"*80)
+print(f"MOOSE run time = {run_time:.3f} seconds")
+print("-"*80)
+
+#%%
+# Now we create our exodus reader by giving it the path to the exodus file we
+# want to read. By default moose creates an exodus output with the input file
+# name with "_out.e" appended.
+output_exodus = output_path / (moose_input.stem + "_out.e")
+exodus_reader = ExodusReader(output_exodus)
+
+print("\nReading exodus file with ExodusReader:")
+print(output_exodus.resolve())
+print()
+
+
+#%%
+# We start with the simplest method which is to just read everything in the
+# exodus file and return it as a ``SimData`` object. In some cases we will not
+# want to read everything into memory so we will show how we can control this n
+# next.
+#
+# We then use a helper function to print the sim data fields to the terminal so
+# we can see the structure of the dataclass. The documentation for the
+# ``SimData`` class provides descriptions of each of the fields and we
+# recommend you check this out to understand the terminal output.
+all_sim_data = exodus_reader.read_all_sim_data()
+print("SimData from 'read_all':")
+sens.SimTools.print_sim_data(all_sim_data)
+
+#%%
+# We are now going to read specific variables from the exodus output using a
+# read configuration object. There are two ways to create this object. A good
+# way to start is to use the exodus reader to return the read config that would
+# extract all variables from the exodus as shown below. This is helpful as it
+# will pre-populate the 'node', 'elem' and 'glob' variables with the appropriate
+# dicitionary keys to read based on what is already in the exodus file.
+
+read_config = exodus_reader.get_read_config()
+sens.SimTools.print_dataclass_fields(read_config)
+
+#%%
+# We set the 'node_vars' field to None to prevent the nodal variables being read
+# from the exodus file. We then use the read function to return a ``SimData``
+# object and we print the 'node_vars' field to verify that it has not been read.
+read_config.node_vars = None
+sim_data = exodus_reader.read_sim_data(read_config)
+
+print("Read config without 'node_vars':")
+print(f"    {sim_data.node_vars=}")
+print()
+
+#%%
+# We can also turn off reading of the simulation time steps, nodal coordinates
+# and the connectivity table by setting these flags to False in our read config.
+read_config.time = False
+read_config.coords = False
+read_config.connect = False
+sim_data = exodus_reader.read_sim_data(read_config)
+
+print("Read config without time, coords and connectivity:")
+print(f"    {sim_data.time=}")
+print(f"    {sim_data.coords=}")
+print(f"    {sim_data.connect=}")
+print()
+
+
+#%%
+# We can also read specific keyed fields from 'node', 'elem' and 'glob'
+# variables. Here we will read just the x displacement from the node variables.
+# Note that for element variables you also need to specify the block number (
+# corresponding to the number X in the key for the connectivity table in the
+# format "connectivityX" in the connectivity dictionary).
+
+read_config.node_vars = ("disp_x",)
+sim_data = exodus_reader.read_sim_data(read_config)
+print("Read config only extracting x displacement:")
+print(f"    {sim_data.node_vars.keys()=}")
+print(f"    {sim_data.node_vars['disp_x'].shape=}")
+print()
+

pyvale/examples/mooseherder/ex7a_read_moose_herd_results.py

@@ -0,0 +1,153 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Reading exodus output from a parameter sweep
+================================================================================
+
+In this example we run a parallel sweep of a moose simulation and then read the
+results of the whole sweep using the sweep reader class.
+
+**Installing moose**: To run this example you will need to have installed moose
+on your system. As moose supports unix operating systems windows users will need
+to use windows subsystem for linux (WSL). We use the proteus moose build which
+can be found here: https://github.com/aurora-multiphysics/proteus. Build scripts
+for common linux distributions can be found in the 'scripts' directory of the
+repo. You can also create your own moose build using instructions here:
+https://mooseframework.inl.gov/.
+
+We start by importing what we need for this example.
+"""
+
+import time
+from pathlib import Path
+import numpy as np
+
+#pyvale imports
+import pyvale.sensorsim as sens
+import pyvale.dataset as dataset
+from pyvale.mooseherder import (MooseHerd,
+                                MooseRunner,
+                                MooseConfig,
+                                InputModifier,
+                                DirectoryManager,
+                                SweepReader,
+                                sweep_param_grid)
+
+#%%
+# In this first section we setup our herd workflow manager to run a parameter
+# sweep of our moose simulation as we have done in previous examples. We run
+# the parameter sweep and print the solve time to the terminal. The sweep
+# output is in the standard pyvale-output directory we have used previously.
+# In the next section we will read the output from the parameter sweep below.
+
+moose_input = dataset.element_case_input_path(dataset.EElemTest.HEX20)
+moose_modifier = InputModifier(moose_input,'#','')
+
+config = {'main_path': Path.home()/ 'moose',
+          'app_path': Path.home() / 'proteus',
+          'app_name': 'proteus-opt'}
+moose_config = MooseConfig(config)
+
+moose_runner = MooseRunner(moose_config)
+moose_runner.set_run_opts(n_tasks = 1,
+                          n_threads = 2,
+                          redirect_out = True)
+
+num_para_sims: int = 4
+dir_manager = DirectoryManager(n_dirs=num_para_sims)
+herd = MooseHerd([moose_runner],[moose_modifier],dir_manager)
+herd.set_num_para_sims(n_para=num_para_sims)
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+dir_manager.set_base_dir(output_path)
+dir_manager.reset_dirs()
+
+moose_params = {"nElemX": (2,3),
+                "lengX": np.array([10e-3,15e-3]),
+                "PRatio":(0.3,0.35)}
+params = [moose_params,]
+sweep_params = sweep_param_grid(params)
+
+
+if __name__ == "__main__":
+    print('Running simulation parameter sweep in parallel.')
+    herd.run_para(sweep_params)
+    print(f'Run time (parallel) = {herd.get_sweep_time():.3f} seconds\n')
+
+
+#%%
+# To read the sweep output files we first create our sweep reader and pass it
+# the same directory manager we used to run the sweep. We also set the number
+# of simulation outputs to read in parallel when we call the read parallel
+# function. We will see below that we can still read sequentially by calling
+# read sequential functions and if the simulation output files are small it is
+# likely to be faster to read them sequentially.
+#
+# We first use our sweep reader to inspect the output path keys to find the
+# simulation output files that exist in the simulation working directories.
+
+sweep_reader = SweepReader(dir_manager,num_para_read=4)
+output_files = sweep_reader.read_all_output_file_keys()
+
+print('Sweep output files (from output_keys.json):')
+for ff in output_files:
+    print(f"    {ff}")
+print()
+
+#%%
+# Using the sweep reader we can read the results for a single simulation chain
+# from the sweep. Our simulation chain only has a single moose simulation so
+# the list of ``SimData`` objects we are returned only has a single element.
+# We then use a helper function to print the contents of the ``SimData`` object
+# to the terminal.
+#
+# We suggest you check out the documentation for the ``SimData`` object as it
+# includes a detailed description of each of the relevant fields you might want
+# to use for post-processing.
+sim_data_list = sweep_reader.read_results_once(output_files[0])
+sens.SimTools.print_sim_data(sim_data_list[0])
+
+#%%
+# We can use the sweep reader to read results for each simulation chain in the
+# sweep sequentially with read sequential function. The sweep results we are
+# returned is a list of list of data classes where the outer list corresponds to
+# the unique simulation chain in the sweep and the inner list corresponds to the
+# the results for the particular simulation tool in the chain.
+#
+# After reading the sweep results we print the inner and outer list lengths. We
+# have 8 unique simulation chains with a single simulation tool (moose) in the
+# chain.
+start_time = time.perf_counter()
+sweep_results_seq = sweep_reader.read_sequential()
+read_time_seq = time.perf_counter() - start_time
+
+print("Outer list = unique simulation chain:")
+print(f"    {len(sweep_results_seq)=}")
+print("Inner list = particular simulation tool in the chain:")
+print(f"    {len(sweep_results_seq[0])=}")
+print("'SimData' object for the particular simulation tool:")
+print(f"    {type(sweep_results_seq[0][0])=}")
+print()
+
+#%%
+# Finally, we read the same sweep in parallel making sure we include a main
+# guard as we will be using the multi-processing package to do this. We then
+# print the read time to the console for the sequential and parallel reads.
+if __name__ == '__main__':
+    start_time = time.perf_counter()
+    sweep_results_para = sweep_reader.read_results_para()
+    read_time_para = time.perf_counter() - start_time
+
+print()
+print("-"*80)
+print(f'Read time sequential = {read_time_seq:.6f} seconds')
+print(f'Read time parallel   = {read_time_para:.6f} seconds')
+print("-"*80)
+print()