Granta MI Scripting Toolkit 4.0

What’s new in Version 4.0

Last update: 16.07.2025

Key features introduced or improved in MI Scripting Toolkit for Python 4.0.

What’s new?

Subsets

Summary

  • If your code does not use the Table.subsets property and the default subset in your tables contain all records, you should see no behavior changes. This is the most common scenario.
  • If your code sets the Table.subsets property to the default subset, then you should disable this assignment from your code, since it now occurs automatically.
  • If your code sets the Table.subsets property to a non-default subset, then you should clear the Table.subsets property with table_object.subsets.clear() before setting the non-default subset.
  • If your code sets the Table.subsets property to a set containing more than one subset and you perform any subsequent record fetching or search operations, these operations will raise a ValueError. They would previously not consider all applied subsets, and so would return incorrect results.

Detailed description of changes

The Table.subsets property defines the applied subset or subsets for a particular table. In previous releases, if the subsets argument was not provided to the Database.get_table() and Database.get_table_by_guid() methods, they returned a Table object with an empty subsets property, which meant that there was no active subset for that table. In this release, calling those methods with an empty subsets argument now returns a Table object with the default subset for that table activated. This causes the following changes in default behavior:

  • Records are now added to the default subset automatically on import.
  • All record fetching operations, table-specific searches and database criteria searches will only consider records in the default subset (see Searching and browsing for records for more details).

A new property default_subset has been added to the Table class, which always contains the default subset as defined in the schema. This can be used to reactivate the default subset with the code:

table.subsets.clear()
table.subsets.add(table.default_subset)

Adding additional subsets to the Table.subsets property is allowed, but a Table in this state can only be used for creating new records. Any attempt to perform a retrieval of records, for example by searching or calling Table.all_records(), will result in a ValueError.

The method Exporter.run_exporter() previously performed some record filtering in rare situations. The behavior has been simplified and now subset filtering is never performed.

Unchanged operations

The subset filtering of LinkFetcher.fetch_linked_records() is unchanged, and optionally filters the results to include only records that are in the default subset of the target table. This is controlled with the optional filter_subsets argument.

The following record fetching and data export operations are unchanged and do not perform any subset filtering:

Reverting to the previous behavior

The previous behavior can be retrieved by supplying subsets={} as an additional argument to Database.get_table(), or by calling clear() on the Table.subsets property before interacting with the Table object.

Searching and browsing for records

Summary

  • All searches except Database.search_for_records_by_text() now apply a subset filter when searching. If a table included in a search has multiple applied subsets, a ValueError is raised.
  • The Table.search_for_records_where() list_of_criteria parameter must now only contain criteria based on pseudo-attributes and attribute definitions from the table being searched. Otherwise a ValueError is raised.
  • The Database.search_for_records_where() list_of_criteria parameter must now only contain criteria based on pseudo-attributes and attribute definitions from at most one table within the database being searched. Otherwise a ValueError is raised.
  • Getting records based on the Granta MI tree is generally now subject to subset filtering. If a table included in a record fetch operation has multiple applied subsets, a ValueError is raised.

Detailed description of changes

The behavior of subsets related to searching and fetching records has been standardized:

Searching with pseudo-attribute criteria

Streamlined API enhancements and bug fixes

Enhancements

Bug fixes

  • Non-Scripting Toolkit names such as Dict and Enum are no longer importable from GRANTA_MIScriptingToolkit.granta.
  • Attempting to use Table.bulk_link_fetch() with a record link group that does not exist in the Table raises a ValueError.
  • A record link group can now be completely cleared for a record by calling Record.set_links() with an empty iterable for the records argument.
  • Setting Record.type for an existing record now raises a ValueError. Record.type can only be set when records are created.
  • When short_name is not provided on Record instantiation, Record.short_name is no longer set to the name argument value. Record.short_name can now be None for new records, in which case the record tree name will default to the record name upon record creation on the server.
  • The children property of records obtained via Record.all_children() and Table.all_records() no longer includes all descendants, and now only includes direct children.
  • Record types excluded via the arguments include_folders or include_generics on Record.all_children() and Table.all_records() are no longer incorrectly excluded in the children property of resulting records.
  • Unit systems now correctly affect tabular attributes:
  • Accessing a AttributeDefinitionTabular or AttributeTabular object linked to a hidden table no longer raises a KeyError.
  • Attempting to call Exporter.get_parameters_required_for_export for an FEA exporter which contains functional meta-attributes no longer raises a KeyError.

Examples

Example notebooks are included in the MI Scripting Toolkit, this is included as part of the Granta MI Enterprise package on the Ansys Customer Portal. Contact your system administrator for more details.

Foundation API enhancements and bug fixes

Backwards incompatible API changes

Streamlined API

The changes described above in Subsets and Searching and browsing for records are breaking changes to the streamlined API. In addition:

AsyncJobs

The AsyncJobQueue functionality has been moved to a new PyAnsys package called PyGranta JobQueue.

If you are using Granta MI 2024 R2 or later, you can use this package to import and export Excel files and import text data into Granta MI. The package can be installed with pip install ansys-grantami-jobqueue, and documentation can be accessed here. The differences between the packages are minimal, and the PyGranta JobQueue API documentation includes a guide for migrating code from Scripting Toolkit AsyncJobs to PyGranta JobQueue.

If you are using Granta MI 2024 R1 or earlier and require Job Queue functionality, you should continue to use Scripting Toolkit v3.3.

Known issues

  • If an attribute is exported with the Table.bulk_fetch method with include_binary_data=False, subsequent values returned by the AttributePicture.mime_file_type property will always return image/png, regardless of the actual image format. The header returned when accessing the URL is unaffected and should be used instead.

  • In version-controlled tables, DataRevisionHistory objects have an ambiguous meaning. The history.last_modified_date for the following attribute types is updated when the release state of the parent record is modified:

    • Date
    • Hyperlink
    • Integer
    • Logical
    • Range
    • Short text

    The history.last_modified_date for the following attribute types is not updated when the release state of the parent record is modified:

    • Discrete
    • File
    • Functional
    • Long text
    • Picture
    • Point
    • Tabular

Connect with Ansys