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

pyvale/examples/mooseherder/ex2a_run_moose_once.py

@@ -0,0 +1,80 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Running MOOSE once
+================================================================================
+
+In this example we will run a single moose simulation from a moose input .i file
+using a 'runner' object.
+
+**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
+
+#pyvale imports
+import pyvale.dataset as dataset
+from pyvale.mooseherder import (MooseConfig,
+                                MooseRunner)
+
+
+#%%
+# First we build our moose configuration which gives the location of our main
+# moose build, our moose app and the name of the app to use when called on the
+# command line.
+config = {'main_path': Path.home()/ 'moose',
+          'app_path': Path.home() / 'proteus',
+          'app_name': 'proteus-opt'}
+moose_config = MooseConfig(config)
+
+#%%
+# We can now build a runner object using our configuration. We can then set some
+# options for the run including parallelisation and if we should redirect
+# terminal output to file. For smaller simulations we are better off using
+# threads for paralleisation as they reduce overhead compared to MPI tasks.
+moose_runner = MooseRunner(moose_config)
+
+moose_runner.set_run_opts(n_tasks = 1,
+                          n_threads = 8,
+                          redirect_out = False)
+
+#%%
+# Let's grab a simple thermo-mechanical cube test case from pyvale's moose
+# simulation library and we will set this as the input file to run with our
+# 'runner'.
+moose_input = dataset.element_case_input_path(dataset.EElemTest.HEX20)
+moose_runner.set_input_file(moose_input)
+
+#%%
+# Our moose runner will pass a list of strings which form the command line to
+# run our moose simulation. We print the list of command line arguments here so
+# we can check we are correctly calling our input file with the run options we
+# want.
+print(moose_runner.get_arg_list())
+print()
+
+#%%
+# To run our moose simulation we just need to call 'run', here we will time our
+# moose run and then print the solve time to the terminal
+start_time = time.perf_counter()
+moose_runner.run()
+run_time = time.perf_counter() - start_time
+
+print()
+print("-"*80)
+print(f'MOOSE run time = {run_time:.3f} seconds')
+print("-"*80)
+print()

pyvale/examples/mooseherder/ex2b_run_gmsh_once.py

@@ -0,0 +1,64 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Running Gmsh once
+================================================================================
+
+In this example we will run a gmsh script to generate a mesh file using the
+GmshRunner class.
+
+**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.
+"""
+
+import time
+from pathlib import Path
+
+#pyvale imports
+import pyvale.dataset as dataset
+from pyvale.mooseherder import GmshRunner
+
+#%%
+# First we need to create a 'runner' for gmsh which needs to know the path to
+# the gmsh executable. You will need to replace this path with the path to where
+# you have install gmsh on your system.
+gmsh_path = Path.home() / 'gmsh/bin/gmsh'
+gmsh_runner = GmshRunner(gmsh_path)
+
+#%%
+# Next we grab a gmsh file from pyvale simulation library and we set this as the
+# input file for our runner.
+gmsh_input = dataset.sim_case_gmsh_file_path(case_num=17)
+gmsh_runner.set_input_file(gmsh_input)
+
+#%%
+# Now we can run gmsh to generate our mesh using the run method, the parse only
+# flag means we will run gmsh head less and not open the gmsh GUI but terminal
+# output will still be written to stdout.
+#
+# We also use our performance timer to time how long our mesh generation takes
+# and then we print this to the console. Note that parallelisation options for
+# gmsh can be controlled in the gmsh .geo script file.
+start_time = time.perf_counter()
+gmsh_runner.run(gmsh_input,parse_only=True)
+run_time = time.perf_counter() - start_time
+
+print()
+print("-"*80)
+print(f'Gmsh run time = {run_time :.3f} seconds')
+print("-"*80)
+print()
+
+#%%
+# The GmshRunner and the MooseRunner implement the SimRunner abstract base
+# class. Later on when we will see that we can use this to run a list of
+# different sim runners in order using MooseHerd workflow manager. This allows
+# us to first build our mesh with gmsh and then run a moose simulation using
+# that mesh. We can also implement our own SimRunner's to add additional pre or
+# post processing steps to our simulation chain.

pyvale/examples/mooseherder/ex2c_run_both_once.py

@@ -0,0 +1,114 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Run Gmsh then MOOSE once
+================================================================================
+
+In this example we use a gmsh runner followed by a moose runner to generate our
+mesh and then run a moose simulation using this mesh. The moose input file needs
+to know the name of the gmsh .msh file which is specified in the gmsh .geo
+script when the Save command is called. It is possible to use the input
+modifiers we have seen previously to update this file name as a variable in the
+moose input script but for this example we have set things manually inside the
+moose input script.
+
+**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.
+"""
+
+import time
+import shutil
+from pathlib import Path
+
+#pyvale imports
+import pyvale.dataset as dataset
+from pyvale.mooseherder import (MooseConfig,
+                                GmshRunner,
+                                MooseRunner)
+
+#%%
+# We need to make sure the output .msh file from gmsh can be found by our moose
+# input script so we are going to put them in our standard pyvale-output
+# directory in our current working directory. First we grab the paths for the
+# .geo and .i and then we copy them to the pyvale-output directory where we will
+# run our simulation from. We then print the paths to we can see where the files
+# are - try opening them with your text editor of choice so you can see how the
+# name of the mesh is specified in the gmsh .geo as the .msh output and the then
+# how the name is matched in the moose .i to read the .msh to run the sim.
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+gmsh_file = dataset.sim_case_gmsh_file_path(case_num=17)
+gmsh_input = output_path / gmsh_file.name
+
+moose_file = dataset.sim_case_input_file_path(case_num=17)
+moose_input = output_path / moose_file.name
+
+shutil.copyfile(moose_file,moose_input)
+shutil.copyfile(gmsh_file,gmsh_input)
+
+print(f"\n{moose_input.resolve()=}")
+print(f"{gmsh_input.resolve()=}\n")
+
+#%%
+# We need to run gmsh first to generate our .msh file so we set it up and run it
+# in exactly the same way as we have done in the previous example. We pass the
+# path to the gmsh executable to our runner. We then set our input file and call
+# run to generate the mesh.
+gmsh_path = Path.home() / 'gmsh/bin/gmsh'
+gmsh_runner = GmshRunner(gmsh_path)
+
+gmsh_runner.set_input_file(gmsh_input)
+
+gmsh_start = time.perf_counter()
+gmsh_runner.run(parse_only=True)
+gmsh_run_time = time.perf_counter()-gmsh_start
+
+#%%
+# Now that we have our mesh we can run our moose simulation. We will setup and
+# run moose in exactly the same was as in a previous example. First, we setup
+# our moose configuration and pass this to our runner. We then set our run /
+# parallelisation options before calling run to extecute the simulation.
+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)
+
+moose_start = time.perf_counter()
+moose_runner.run()
+moose_run_time = time.perf_counter() - moose_start
+
+#%%
+# Finally we print the execution times of both runners and print these to the
+# console.
+print("-"*80)
+print(f'Gmsh run time = {gmsh_run_time:.2f} seconds')
+print(f'MOOOSE run time = {moose_run_time:.2f} seconds')
+print("-"*80)
+print()
+
+

pyvale/examples/mooseherder/ex3_run_moose_seq_para.py

@@ -0,0 +1,157 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Running a parameter sweep of a MOOSE simulation
+================================================================================
+
+In this example we will perform a parameter sweep of a moose simulation showing
+the capability of the 'herder' workflow manager which can be passed a list of
+'input modifiers' and 'runners'. The 'herder' will then use the 'input
+modifiers' to update simulation parameters and then call the respective 'runner'
+using the modified input file. In this example we will also see that the
+'herder' can be used to execute a parameter sweep sequentially or in parallel.
+
+**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.
+"""
+
+from pathlib import Path
+import numpy as np
+
+#pyvale imports
+import pyvale.dataset as dataset
+from pyvale.mooseherder import (MooseHerd,
+                                MooseRunner,
+                                InputModifier,
+                                DirectoryManager,
+                                MooseConfig,
+                                sweep_param_grid)
+
+#%%
+# First we are going to setup an input modifier and a runner for our moose
+# simulation. Here we need to make sure that when we set our moose
+# parallelisation options we leave enough threads for all the simulations that
+# are running at once base on our CPU. It is also helpful to redirect stdout to
+# file so that our terminal does not become a mess when we start running our
+# simulations in parallel.
+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)
+
+#%%
+# Now we are going to create a directory manager which will be used to make sure
+# our simulations are run in separate directories. We then create our herd
+# workflow manager with our list of runners and corresponding input modifiers.
+# In our case we are only running moose so our lists have a single item. The
+# last thing we do is specify the number of simulations we want to run in
+# parallel, for this case we match the number of directories.
+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 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.reset_dirs()
+
+#%%
+# We now need to generate the parameter combinations we want to run using our
+# 'herd'. This is given as a list of list of dictionaries where the outer list
+# corresponds to the unique simulation chain, the inner list corresponds to each
+# simulation runner in the chain, and the dicitionary contains key value pairs
+# where the keys are the variables names to edit in the input file. For this
+# case we only have moose in our simulation chain so our inner list will only
+# have a length of one but in the next example we will see how we can combine
+# a parameter sweep with gmsh->moose sweeping all possible combinations of
+# variables for both simulation tools.
+#
+# For now we are going to use a helper function from mooseherder which will
+# generate all possible combination for us in the correct data format. We just
+# provide a dictionary of lists of unique parameters we want to analyse. Finally
+# we print the unique combinations of parameters to the terminal as well as the
+# total number of simulations to check everything is working as expected.
+
+moose_params = {"nElemX": (2,3,4),
+                "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()
+
+#%%
+# 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/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()