Substance compliance#

Query definition#

class SubstanceComplianceQuery#

Evaluate compliance for Granta MI substance records against a number of indicators.

All methods used to add substances and indicators to this query return the query itself so that they can be chained together as required. Records can be added using a combination of any of the available methods.

Once the query is fully constructed, use the cxn. run() method to return a result of type SubstanceComplianceQueryResult.

Notes

The amount of a substance is a critical factor when determining if it is compliant or non-compliant with a legislation. For the other compliance queries in this API, the amount of substance is determined by the value set in the declaration stored in Granta MI. However, when performing a query for substance compliance, there is no declaration because the substances are being examined directly.

As a result, a set of extra methods are defined that allow the amount of each substance to be defined along with the reference to the record in Granta MI. These methods have the name _with_xxxxxx_and_amounts() and take a list of tuples as the argument.

Examples

>>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
>>> indicator = WatchListIndicator(
...     name="Prop 65",
...     legislation_ids=["Prop65"]
... )
>>> query = (
...     SubstanceComplianceQuery()
...     .with_cas_numbers_and_amounts([('50-00-0', 25), ('57-24-9', 0.5)])
...     .with_indicators([indicator])
... )
>>> cxn.run(query)
<SubstanceComplianceQueryResult: 2 SubstanceWithCompliance results>

with_indicators(indicators)#

Add a list or set of WatchListIndicator or RoHSIndicator objects to evaluate compliance against.

Parameters:

indicatorslist[WatchListIndicator | RoHSIndicator]: List of indicators.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described above.

Examples

>>> indicator = WatchListIndicator(
...     name="Prop 65",
...     legislation_ids=["Prop65"]
... )
>>> MaterialComplianceQuery().with_indicators([indicator])
<MaterialCompliance: 0 materials, batch size = 100, 1 indicators>

with_cas_numbers_and_amounts(cas_numbers_and_amounts, external_database_key=None)#

Add a list or set of CAS numbers and amounts to a substance query.

The CAS numbers and quantity pairs are expressed as a tuple, with the quantity in units of wt. %.

If the records referenced by values in the cas_numbers_and_amounts argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

cas_numbers_and_amountslist[tuple[str, float]] | set[tuple[str, float]]: List or set of CAS numbers and amounts expressed as a tuple.
external_database_keystr, optional: Required if records referenced by the cas_numbers_and_amounts argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery()
>>> query = query.with_cas_numbers_and_amounts([('50-00-0', 25), ('57-24-9', 0.1)])
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_ec_numbers_and_amounts(ec_numbers_and_amounts, external_database_key=None)#

Add a list or set of EC numbers and amounts to a substance query.

The EC numbers and quantity pairs are expressed as a tuple, with the quantity in units of wt. %.

If the records referenced by values in the ec_numbers_and_amounts argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

ec_numbers_and_amountslist[tuple[str, float]] | set[tuple[str, float]]: Listor set of EC numbers and amounts expressed as a tuple.
external_database_keystr, optional: Required if records referenced by the ec_numbers_and_amounts argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery()
>>> query = query.with_ec_numbers_and_amounts([('200-001-8', 25),
...                                            ('200-319-7', 0.1)])
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_chemical_names_and_amounts(chemical_names_and_amounts, external_database_key=None)#

Add a list or set of chemical names and amounts to a substance query.

The chemical names and quantity pairs are expressed as a tuple, with the quantity in units of wt. %.

If the records referenced by values in the chemical_names_and_amounts argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

chemical_names_and_amountslist[tuple[str, float]] | set[tuple[str, float]]: List or set of chemical names and amounts expressed as a tuple.
external_database_keystr, optional: Required if records referenced by the chemical_names_and_amounts argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery()
>>> query = query.with_chemical_names_and_amounts([('Formaldehyde', 25),
...                                                ('Strychnine', 0.1)])
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_cas_numbers(cas_numbers, external_database_key=None)#

Add a list or set of CAS numbers to a substance query.

The amount of substance in the material is set to 100%.

If the records referenced by values in the cas_numbers argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

cas_numberslist[str] | set[str]: List or set of CAS numbers.
external_database_keystr, optional: Required if records referenced by the cas_numbers argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery().with_cas_numbers(['50-00-0', '57-24-9'])
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_ec_numbers(ec_numbers, external_database_key=None)#

Add a list or set of EC numbers to a substance query.

The amount of substance in the material is set to 100%.

If the records referenced by values in the ec_numbers argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

ec_numberslist[str] | set[str]: List or set of EC numbers.
external_database_keystr, optional: Required if records referenced by the ec_numbers argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery().with_ec_numbers(['200-001-8', '200-319-7'])
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_chemical_names(chemical_names, external_database_key=None)#

Add a list or set of chemical names to a substance query.

The amount of substance in the material is set to 100%.

If the records referenced by values in the chemical_names argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

chemical_nameslist[str] | set[str]: List or set of chemical names.
external_database_keystr, optional: Required if records referenced by the chemical_names argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery().with_chemical_names(['Formaldehyde', 'Strychnine'])
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_record_guids_and_amounts(record_guids_and_amounts, external_database_key=None)#

Add a list or set of record GUIDs and amounts to a substance query.

The GUID and quantity pairs are expressed as a tuple, with the quantity in units of wt. %.

If the records referenced by values in the record_guids_and_amounts argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

record_guids_and_amountslist[tuple[str, float]] | set[tuple[str, float]]: List or set of record GUIDs and amounts expressed as a tuple.
external_database_keystr, optional: Required if records referenced by the record_guids_and_amounts argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery()
>>> query = query.with_record_guids_and_amounts(
...     [('bdb0b880-e6ee-4f1a-bebd-af76959ae3c8', 25),
...      ('a98cf4b3-f96a-4714-9f79-afe443982c69', 0.1)]
... )
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_record_history_guids_and_amounts(record_history_guids_and_amounts, external_database_key=None)#

Add a list or set of record history GUID and amounts to a substance query.

The GUID and quantity pairs are expressed as a tuple, with the quantity in units of wt. %.

If the records referenced by values in the record_history_guids_and_amounts argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

record_history_guids_and_amountslist[tuple[str, float]] | set[tuple[str, float]]: List or set of record history GUIDs and amounts expressed as a tuple.
external_database_keystr, optional: Required if records referenced by the record_history_guids_and_amounts argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described above.

Examples

>>> query = SubstanceComplianceQuery()
>>> query = query.with_record_history_guids_and_amounts(
...     [('bdb0b880-e6ee-4f1a-bebd-af76959ae3c8', 25),
...      ('a98cf4b3-f96a-4714-9f79-afe443982c69', 0.1)]
... )
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_record_history_ids_and_amounts(record_history_identities_and_amounts, external_database_key=None)#

Add a list or set of record history identities and amounts to a substance query.

The identity and quantity pairs are expressed as a tuple, with the quantity in units of wt. %.

If the records referenced by values in the record_history_identities_and_amounts argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

record_history_identities_and_amountslist[tuple[int, float]] | set[tuple[int, float]]: List or set of record hirstory identities and amounts expressed as a tuple.
external_database_keystr, optional: Required if records referenced by the record_history_identities_and_amounts argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = SubstanceComplianceQuery()
>>> query = query.with_record_history_ids_and_amounts([(15321, 25), (17542, 0.1)])
<SubstanceComplianceQuery: 2 substances, batch size = 500, 0 indicators>

with_record_guids(record_guids, external_database_key=None)#

Add a list or set of record GUIDs to a query.

If the records referenced by values in the record_guids argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

record_guidslist[str] | set[str]: List or set of record GUIDs.
external_database_keystr, optional: Required if records referenced by the record_guids argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = MaterialComplianceQuery()
>>> query = query.with_record_guids(['bdb0b880-e6ee-4f1a-bebd-af76959ae3c8',
>>>                                  'a98cf4b3-f96a-4714-9f79-afe443982c69'])
<MaterialCompliance: 2 materials, batch size = 100, 0 indicators>

with_record_history_guids(record_history_guids, external_database_key=None)#

Add a list or set of record history GUIDs to a query.

If the records referenced by values in the record_history_guids argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

record_history_guidslist[str] | set[str]: List or set of record history GUIDs.
external_database_keystr, optional: Required if records referenced by the record_history_guids argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> query = MaterialComplianceQuery()
>>> query.with_record_history_guids(['41e20a88-d496-4735-a177-6266fac9b4e2',
>>>                                  'd117d9ad-e6a9-4ba9-8ad8-9a20b6d0b5e2'])
<MaterialCompliance: 2 materials, batch size = 100, 0 indicators>

with_record_history_ids(record_history_identities, external_database_key=None)#

Add a list or set of record history identities to a query.

If the records referenced by values in the record_history_identities argument are stored in an external database, you must provide the external database key using the external_database_key argument. See Using external records in analysis for more details.

Parameters:

record_history_identitieslist[int] | set[int]: List or set of record history identities.
external_database_keystr, optional: Required if records referenced by the record_history_identities argument are stored in an external database.

Added in version 2.4.

Returns:

Query: Current query object.

Raises:

TypeError: Error to raise if the method is called with values that do not match the types described earlier.

Examples

>>> MaterialComplianceQuery().with_record_history_ids([15321, 17542, 942])
<MaterialCompliance: 3 materials, batch size = 50, 0 indicators>

with_batch_size(batch_size)#

Set the number of records to include in a single request for this query.

Default values are set based on typical usage of the Restricted Substances database. This value can be changed to optimize performance on a query-by-query basis if required. For example, you can change it if certain records contain particularly large or small numbers of associated records.

Parameters:

batch_sizeint: Number of records to include in a single request to Granta MI.

Returns:

Query: Current query object.

Raises:

ValueError: Error to raise if the batch size is set to a number less than 1.
TypeError: Error to raise if a value of any type other than int is specified.

Notes

The Restricted Substances database makes extensive use of tabular data and associated records to store the complex hierarchical relationships that define compliance of products, assemblies, parts, specifications, and materials. As a result, it is impossible to determine the complexity of a particular query without knowing precisely how many records are related to the record included in the query.

The default batch sizes are set for each record type and represent appropriate numbers of those records to be included in the same request assuming typical numbers of associated records.

Even if the records are queried in multiple batches, the results are assembled into a single result object.

Examples

>>> MaterialComplianceQuery().with_batch_size(50)
<MaterialCompliance: 0 materials, batch size = 50, 0 indicators>

Query result#

class SubstanceComplianceQueryResult(results, indicator_definitions, messages)#

Retrieves the result of running the SubstanceComplianceQuery class.

This class describes the compliance status of substances against one or more indicators.

compliance_by_indicator#

Compliance status for each indicator in the original query. The indicator name is used as the dictionary key.

The result for each indicator is determined by taking the worst result for that indicator across all items included in the query.

Returns:

dict[str, WatchListIndicator | RoHSIndicator]

Examples

>>> compliance_result: MaterialComplianceQueryResult
>>> compliance_result.compliance_by_indicator
{'Prop 65': <WatchListIndicator,
        name: Prop 65,
        flag: WatchListFlag.WatchListAboveThreshold>
}

compliance_by_substance_and_indicator#

Compliance status for each substance specified in the original query.

Returns:

list[SubstanceWithComplianceResult]

Examples

>>> result: SubstanceComplianceQueryResult
>>> result.compliance_by_substance_and_indicator
[<SubstanceWithComplianceResult({"cas_number": 50-00-0}), 1 indicators>, ...]

messages#

Messages generated by Granta MI when running the query. The presence of one or more messages means that something unexpected happened when running the query but that the query could still be completed.

Messages are sorted in order of decreasing severity and are available in the Service Layer log file.

Messages are also logged using the Python logging module to the ansys.grantami.bomanalytics logger. By default, messages with a severity of "warning" or higher are printed on stderr.

Substance result#

class SubstanceWithComplianceResult(percentage_amount, **kwargs)#

Retrieves an individual substance included as part of a compliance query result. This object includes three categories of attributes:

The reference to the substance in Granta MI
The compliance status of this substance, stored in a dictionary of one or more indicator objects
The amount of the substance present in the parent item

property record_history_identity: int | None#: Record history identity.

property record_history_guid: str | None#: Record history GUID.

property record_guid: str | None#: Record GUID.

property database_key: str | None#

The database key for the database that contains the record.

This property is only populated if the record is in a different database to the one specified in BomAnalyticsClient.set_database_details(). Supported by MI Restricted Substances and Sustainability Reports 2026 R1 or later.

Added in version 2.4.

property identity: str | None#

Item unique identifier.

This property is only populated on BoM query results and is equal to the id attribute of the corresponding input BoM item. If no id has been defined on the BoM item, a unique auto-generated value is assigned during analysis.

property external_identity: str | None#

Item external identity.

This property is only populated on BoM query results and is equal to the <ExternalIdentity> element of the corresponding input BoM item.

property name: str | None#

Item name.

This property is only populated on BoM query results and is equal to the <Name> element of the corresponding input BoM item.

property cas_number: str | None#: CAS number.

property ec_number: str | None#: EC number.

property chemical_name: str | None#: Chemical name.

property equivalent_references: list[SubstanceReference] | None#

Other substance records which are defined as being equivalent to this record.

Only populated if this record is a substitute for a record in a different database during analysis via a cross-database link.

Added in version 2.4.

property indicators: Dict[str, WatchListIndicator | RoHSIndicator]#: Compliance status of this item for each indicator included in the original query.

property percentage_amount: float | None#: Percentage amount of this substance in the parent item.

Added in version 2.1.