This guide will demonstrate the basics of using CML Compiler, including how to use the tool through the command prompt. Throughout this article there will be links to more detailed articles which can aid in using the tool. This article contains information on how the tool is used when generating CMLs for INTERCONNECT. For information about how the tool is used to generate CMLs for Verilog-A CMLs, please see CML Compiler command line interface for Verilog-A CMLs.
It's assumed at this point that CML Compiler is already installed, for information on how to install CML Compiler, see Installing CML Compiler.
New users of CML Compiler may find it instructive to work through a step-by-step guide to understand the general workflow of the tool. For a step-by-step example of how CML Compiler is used to create a custom CML, see Creating a Custom CML.
Launching CML Compiler
CML Compiler is a command line tool. Follow the instructions below to launch a terminal with the environment set-up for your CML Compiler session.
On Windows, from the "Start" menu, you can choose to launch CML Compiler. This will launch a terminal from the library directory where CML Compiler was last launched. Alternatively, you can choose to launch the "Lumerical <version> Launcher" and click on "New Project" for "CML Compiler" under the "Products" tab or launch CML Compiler from a previous project location under the "Recent" tab. These two approaches will both start a terminal with environment automatically set up.
[[Note:]] Optionally, an advanced user could choose to launch a terminal of his/her choice (eg. cmd, Powershell), provided that you set up the PATH environment variable manually (please refer to the section Advanced Windows Set-up (Optional)). |
On Linux, please launch a terminal in either "Bash" or "CSH" and open the "Lumerical Launcher" by entering:
launcher
You can either then choose to click on "New Project" for "CML Compiler" under the "Products" tab or launch CML Compiler from a previous project location under the Recent tab.
[[Note:]] The terminal will only be able to find the "launcher" if it is added to PATH after installation (see Installing CML Compiler). Advanced users can alternatively launch CML Compiler from a terminal directly as opposed to starting the launcher. |
The Command Line Interface for INTERCONNECT CMLs
CML Compiler is controlled through a terminal (ie - cmd or Powershell on Windows and BASH or CSH on Linux) using a command line interface. The tool is used by running the following command:
cml-compiler
Running the following displays a general help menu:
cml-compiler --help
The "--help" argument can be appended to any positional argument accepted by the cml-compiler command to display information about how to use that argument. Below are the positional arguments which can be used with cml-compiler, each of which can be used with the following syntax:
cml-compiler template
cml-compiler rename
cml-compiler delete
cml-compiler validate
cml-compiler library
cml-compiler install
cml-compiler test
cml-compiler all
cml-compiler runtests
cml-compiler status
cml-compiler support
cml-compiler update_data_format
For convenience, the tool can be run using scripts (ie. Batch files on Windows (.bat) or shell scripts on Linux (.sh))to avoid having to regularly use the command line interface. For more information on preparing scripts to run CML Compiler, see Alternative Running Options.
[[Note:]] In Linux only, any whitespace in the file path needs to be replaced by a backslash (\) for file paths within quotes or by a double backslash (\\) for file paths without quotes. For example, if the destination directory has a folder named ‘Test folder’ with a file path “/home/developer/Documents/Test folder" then the appropriate syntax for the file path when used with CML Compiler would be “/home/developer/Documents/Test\folder” or /home/developer/Documents/Test\\folder for the case when the file path is specified without quotes. For example, the syntax for template and delete commands command would be, cml-compiler template -d “/home/developer/Documents/Test\folder” or cml-compiler template -d /home/developer/Documents/Test\\folder. cml-compiler delete --folder “/home/developer/Documents/Test\folder” or cml-compiler delete --folder /home/developer/Documents/Test\\folder . |
template
Running CML Compiler with the "template" argument will create a folder and deploy the default "lumfoundry_template" packaged with CML Compiler installation.
cml-compiler template [-d <destination_directory>]
If you need to deploy a template library with a foundry template name other than the default name, “lumfoundry_template”, the following syntax can be used:
cml-compiler template -–foundry_name <foundry_template_name>
The command also supports deploying a single element or a partial list of elements from the lumfoundry_template library rather than the entire library. This is useful when you want to add new templates to an existing library and modify them to your needs. In this case, the command should be run within the existing library foundry directory (where the library XML file exists) to ensure the element source files are deployed properly. Alternatively, the path to the library foundry directory can be given with the -d option as explained above.
The following syntax can be used for deployment of a partial list of elements from the template library:
cml-compiler template --element_list <element_name_1>, <element_name_2>, …
where element_name_1, element_name_2, etc should be names of templates available in Lumfoundry Template Directory. If an element with the same name already exists in the library, the new element will be deployed with the same name as the element but with a suffix of “_new” to avoid overwriting the existing element (unless you provide a new name using the --rename argument explained below). Running the command with --element_list option without providing any element names will printout a complete list of available template names that could be used for deployment.
If you need to deploy a template element with a name other than its default name, the following syntax can be used for this purpose:
cml-compiler template --element_list <element_name_1>, <element_name_2>, … --rename <element_1_new_name>, <element_2_new_name>, …
Note: As per our recommended practice, please run all the commands in the following sections within the foundry directory. If you do not have foundry directory, please run the above command to create a default foundry directory. Please refer to Lumfoundry Template Directory for more information regarding our default model templates. |
rename
The ‘rename’ command can be used to rename an existing element or template in the library to a desired name. Using this command can avoid manually editing the element source files and the library XML file in order to change the name of an element. The syntax for the command is as follows:
cml-compiler rename <existing_name>, <new_name>
This command can only rename one element at a time. In addition, the command should be run within the existing library foundry directory (where the library master json file exists) to ensure the library in which the element exists, and its source files, can be located properly.
If the element exists in more than one library master .json files, this command automatically updates the element name in all master .json files. If the new element name already exists in another master .json file, then that master .json file is not updated.
Please note that using the ‘rename’ command with a library master file in .XML file format would change the library master file from .XML to .json format with the new updated element name. (Library master files in .XML formats are deprecated and .json format is currently supported). If an element exists in multiple .XML files, this command updates only the chosen .XML master file and leaves other .XML files as is.
The path to the library foundry directory can be given with the --foundry option as shown below:
cml-compiler rename <existing_name>, <new_name> --foundry <directory_path>
The command also takes an optional --format or-f argument which can be used to specify the parameter file format for the element to be renamed. If this option is not provided, the default entry (lsf) will be used. Accepted entries are ‘lsf’ and ‘json’ and the syntax is shown below:
cml-compiler rename <existing_name>, <new_name> --format lsf
Please also note that white spaces are not accepted in element names, element names must begin with an alphabetic character and only contain alphanumeric characters or _ (underscore).
[[Note:]] In case the element renamed using this command has been used by a compound element in your library, you might have to manually edit your compound element source files to ensure the name change has been properly adjusted for that element so that the compound element will be built successfully. This is not the case for container elements having the renamed element as their children. For container elements, the renaming of the children will be handled automatically when you run the command. |
validate
Running cml-compiler with 'validate' command performs data validation of the source data for the elements in the library. This is a preliminary step before building a compact model library. During the ‘validate’ step, source data files provided by the user in ‘.json’, ‘.mat’ or ‘ .lsf’ formats are validated for each element based on the specified photonic model. This includes checking if the required data are present and are in the correct format. This step is automatically performed with “all” and “library” commands.
A user also has the option to validate a single element or multiple elements from an XML file using the following argument.
cml-compiler validate --element_list <element_name>.
Here <element_name> can be replaced with the chosen XML element names separated by a space.
delete
This command enables the user to delete any chosen element from the list of library to be built. By default, the command will only remove the corresponding entry from the library XML file which avoids the element to be included in the library build process. However, if the user wants to delete the element source files and folder from the library source files, the optional “--delete_files” or “-f” argument can be used. Note that with this option, any files included in the element source folders will be deleted and the action would be irreversible. The syntax for this command with the optional file deletion argument is shown below:
cml-compiler delete <element_name_1> <element_name_2> … --delete_files
More than one element can be deleted with the same command by separating the elements names with a whitespace as shown above. Also note that the command should be run within the existing library foundry directory (where the library XML file exists). Alternatively, the path to the library foundry directory can be given with the --foundry option.
[[Note:]] In case the element deleted using this command was being used by a compound or container element in your library, you may have to manually edit your compound/container element source files to ensure that the element deletion is not going to adversely affect the build process of the compound/container element. |
library
Running CML Compiler with the "library" argument will compile a compact model library. This must be done from the top-level of the foundry directory. When the "library" argument is provided, CML Compiler will read the XML data file provided, validate the source data (as in validate command) and then compile all of the elements specified using data from the source folder. Once the tool is finished, it will output the following files:
- /artifacts/interconnect/<library>.cml
- /artifacts/interconnect/library_files/<library>.lib
- /artifacts/interconnect/library_files/<library>.sec
- /artifacts/interconnect/library_files/<library>.spi
- /cml-compiler.state
For example, when the library command is run within Lumfoundry Template, it will generate the following files:
- /artifacts/interconnect/lumfoundry_template.cml
- /artifacts/interconnect/library_files/lumfoundry_template.lib
- /artifacts/interconnect/library_files/lumfoundry_template.sec
- /artifacts/interconnect/library_files/lumfoundry_template.spi
- /cml-compiler.state
The <library>.cml file is the compact model library file, which can be imported as an INTERCONNECT design kit. It contains encrypted models, and is the file to be distributed to end users.
The <library>.lib file is the library file for Monte Carlo and Corner Analysis. It contains information on the statistical parameter distributions and the corners. NOTE: It is not necessary to distribute this file to CML users, as an encrypted version of this file is automatically packaged in the CML.
The <library>.sec file is the library file for Monte Carlo and Corner Analysis using Cadence platform and includes library information necessary to perform statistical analysis in this platform.
The <library>.spi file is the netlist file needed for Tanner L-Edit & INTERCONNECT layout driven flow. It contains information about library elements, their parameters and any other information needed to perform simulations using this flow. Just like the .lib file, it is not necessary to distribute the .sec and .spi files to CML users, as a copy of these files is automatically packaged in the CML.
The cml-compiler.state file is a json-formatted log file generated in the foundry directory (e.g. 'lumfoundry_template'). This contains a report describing whether the data provided for each foundry element meets the format required by the model implemented. It can be used to help troubleshoot errors that are encountered while building an element.
For more information on the working directory folder and file structure, see Lumfoundry Template Directory.
This argument supports following subcommands:
cml-compiler library –-element_list <element_name>
Using this command, you can specify which elements in the XML file you wish to build. Replace <element_name> with the names of as many elements as needed in a space separated manner.
cml-compiler library –-interconnect_virtuoso
Using this command, CML Compiler will build Virtuoso symbol library for the compiled library. This command is only supported on Linux. For more information, please see Virtuoso Library Option for INTERCONNECT CML.
install
Running CML Compiler with the "install" argument will install the compact model library stored in the artifacts folder. When the "install" argument is provided, CML Compiler will locate the compact model library file ("/artifacts/interconnect/<library>.cml"), and install it as a Design Kit within INTERCONNECT.
In order to run this command successfully, CML Compiler must already have access to the <library>.cml artifact. This means that it assumes the tool has already been run with either the "library" or "all" arguments.
test
Running CML Compiler with the "test" argument will create QA tests for all of the elements specified within the XML Data file. When the "test" argument is provided, CML Compiler will read the XML Data file provided, and then create all of the QA Test files for each model within the source folder. Running the tool with this argument will create multiple files within each model's subdirectory.
- /source/<model>/<model>_INTC_test.lsf
- /source/<model>/QA/*.lsf
Where /QA/*.lsf are constituent script files used for QA tests, and <model>_INTC_test.lsf is a top-level QA test script which will run all of the QA tests for a single element.
For more information about running QA tests, see Running QA Tests.
This argument supports following subcommands:
cml-compiler test –-element_list <element_name>
Using this command, you can specify which elements in the XML file you wish to build tests for. Replace <element_name> with the names of as many elements as needed in a space separated manner.
cml-compiler test –-clean
Using this command, CML Compiler will remove all existing QA tests for elements present in the XML file.
all
Running CML Compiler with the "all" argument will build the compact model library, install it as a Design Kit within INTERCONNECT, and then create QA Test files for each model. This is identical to running CML Compiler with the "library", "install" and "test" arguments in succession.
This argument supports following subcommands:
cml-compiler all –-element_list <element_name>
Using this command, you can specify which elements in the XML file you wish to build. Replace <element_name> with the names of as many elements as needed in a space separated manner.
cml-compiler all –-interconnect_virtuoso
Using this command, CML Compiler will build Virtuoso symbol library for the compiled library. This command is only supported on Linux. For more information, please see Virtuoso Library Option for INTERCONNECT CML.
runtests
Running CML Compiler with the "runtests" argument will run the QA tests for all elements within the XML Data file. This argument requires more information to run effectively - In order to run the QA tests for all models, run the following command on Windows:
cml-compiler runtests
And following command on Linux:
cml-compiler runtests --interconnect
For more information on running QA tests with CML Compiler, see Running QA Tests.
This argument supports following subcommands:
cml-compiler runtests –-element_list <element_name>
Using this command, you can specify which elements in the XML file you wish to run tests for. Replace <element_name> with the names of as many elements as needed in a space separated manner.
status
Running CML Compiler with the "status" argument will generate a list of the pass/fail state for the data validation, model building, testbench building, and QA tests for all elements within the XML Data file.
Note that if the data validation, model building, testbench building, or QA testing has not been completed for a particular element, the result will show “N/A” or not available.
If there are multiple XML Data Files, CML Compiler will list the xml options to choose from within the current folder. If you would like to specify which one to use in the command line, this can be done using the -t option as follows:
cml-compiler status -t path/to/datafile.xml
This argument also supports the following subcommand:
cml-compiler status --element_list <element_name>
Using this command, you can specify which elements in the XML file you wish to generate the status report for. Replace <element_name> with the names of as many elements as needed in a space separated manner.
Finally, you can clear the status of elements using the following option:
cml-compiler status --clear_status
Any previously stored pass/fail results from data validation, model building, testbench building, and QA tests will be removed. This option can work in conjunction with the “--element_list” subcommand described above.
Update_data_format
Since 2023 R2.1, following major changes are added to CML Compiler:
- To provide a more consistent user experience, the source data for all the photonic models now adopt a new data format that is formalized in JSON.
- The library master file which stores indices of the elements to be generated and the meta data for the compact model library, is also formalized in JSON.
Although backward compatibility for legacy data format is currently supported (until 2024 R2), the new data format is required for using CML Compiler GUI.
To update directories created before 2023 R2 to the new data format, please use following CML Compiler command line option:
cml-compiler update_data_format
Running this command in a CML Compiler directory, the user is prompted to select a library data file, and CML Compiler will perform the following updates:
- If the library data file is in legacy xml format, it will automatically be converted to json format and the legacy file will be renamed with ”_legacy” tag.
- If the source data for elements listed in the library file are in legacy format, they will be converted to the new format and saved in a .json format and old data files will be renamed with a “_legacy” tag.
- If the source data format is updated for any of the elements, the “parameter_fileformat” entry in the library data file for this element will be removed because “json” is the default parameter file format.
The following syntax can also be used to update the data format for a partial list of elements:
cml-compiler update_data_format --element_list <element_nam_1> <element_name_2> …
Once the data format is successfully updated, the directory is ready to be used by CML Compiler GUI for compact model generation. To learn more, please refer to Using CML Compiler GUI.
Virtuoso Library Option for INTERCONNECT CML
Auto-generated Virtuoso library
As a step to support interoperability, CML Compiler supports the option of generating a Virtuoso library for use of circuit designs and simulations through Cadence Virtuoso environment. To run a co-simulation or ONA/OTRAN analyses, an end-user requires both the INTERCONNECT CML and the Virtuoso library. The Virtuoso library can be auto-generated by CML Compiler via the following commands:
cml-compiler all --interconnect_virtuoso
cml-compiler library --interconnect_virtuoso
A Virtuoso library, Virtuoso_INTERCONNECT_interop, will be created under artifacts folder. This library consists of Virtuoso symbols for the INTERCONNECT CML, with proper Component Description Format (CDF) setup that maps each Virtuoso symbol with its corresponding compact model.
The “library --interconnect_virtuoso” command simply create the INTERCONNECT CML and Virtuoso library, whereas the “all --interconnect_virtuoso” command will additionally install the corresponding INTERCONNECT CML to INTERCONNECT directly.
For instructions on how to load this library to Virtuoso, please refer to Loading a PDK for Cadence interop. To learn more about the generated Virtuoso library, you may optionally refer to Element mapping rules for Cadence interop. To learn more about Cadence Virtuoso Interoperability and co-simulation, please refer to Cadence interoperability overview.
Map INTERCONNECT CML with a custom Virtuoso library
For users who want to map the INTERCONNECT CML with a custom Virtuoso library, please refer to Element mapping rules for Cadence interop for instruction. To help users for such a need, the “--interconnect_virtuoso” sub-command also generates a CDF mapping data file as a reference, which can be found in: /artifacts/Virtuoso_INTERCONNECT_interop/ CDF_setup_reference.json. The data file lists all built components in json format and for each component it lists the CDF setup for ComponentParameters and SimulationInformation, as well as element’s port information which could be helpful for custom graphic symbols.
[[Note:]] To run CML Compiler for creating Virtuoso symbols, user needs to have "95551 Virtuoso Photonics Platform" license for Cadence Virtuoso. Besides, the tool needs to know the directory of Virtuoso on the system. The first time you run CML-Compiler for creating Virtuoso symbols, you will be prompted to provide the path and it will be saved for the next runs. If you wish to change the path, please change virtuoso_home entry in Home/<user>/.config/cml-compiler.json file. |
Alternative Running Options
CML Compiler can be run using scripts instead of the command line interface. In Linux, this is done using shell scripts, and in windows it is done using batch files.
Running CML Compiler using Windows Batch Files
Open a text editor and copy the following lines into a new text file for case of INTERCONNECT CML:
@echo off
call "path_to\\CML Compiler\\bin\\cml-compiler" all
pause
Where "path_to" is replaced with the Lumerical install directory. Save the file into the foundry directory with the extension .bat (e.g. "CML_compiler.bat"). CML Compiler can now be run by simply executing this file, either through the terminal or by double-clicking it from windows explorer.
Running CML Compiler using Linux Shell Scripts
Open the terminal in the foundry directory. Start a new shell script file using nano:
nano run_cml_compiler.sh
When the file is open, copy the following lines into the shell script for case of INTERCONNECT CML:
#!/bin/bash
"path_to/CML Compiler/bin/cml-compiler" all
Where "path_to" is replaced with the lumerical install directory. Finally, CML Compiler can be run by executing the shell script with the following terminal command:
sh run_cml_compiler.sh
For information on how to create a custom compact model library, see Creating a Custom CML.
Launch Support Page
A quick short-cut to launch this webpage in your default browser from the terminal:
cml-compiler support
Command line log file
The CML Compiler will generate a log file named cml-compiler.log under the current working directory where it is getting run. If the file already exists, it will append the new log information to the last line of the file. This file is intended to keep a record of the command line interface actions during the compilation process and can be used for debugging purposes on any failures or forwarded to technical support to better understand the actions leading to any issues during a CML Compiler session. It can be opened and viewed in most text editor software packages. Note that if you change the working directory of CML Compiler, a new log file will be generated (if one doesn’t exist already) in that location. The information in the log file would also have data and time stamps to indicate the time at which each event has occurred. A sample representation of the information typically recorded in the log file is shown below:
########################################################START OF LOG SESSION##############################################################
CURRENT DATE AND TIME: 30/01/2023 11:13:20
CML Compiler executable path: C:\CMLC\cml-compiler\bin\\cml-compiler
Executed command: cml-compiler rename apd_c a_apd
30/01/2023 11:13:20 >>> Found multiple .xml files:
[1]lumfoundry_template.xml,
[2]lumfoundry_template_basic.xml,
[3]lumfoundry_template_statistical.xml,
Please enter one of the above(1-3): 1
30/01/2023 11:13:22 Renaming element...
30/01/2023 11:13:22 CML Compiler executed with specification defined in lumfoundry_template.xml
#########################################################END OF LOG SESSION###############################################################