runtime/manager_help.txt - third_party/opencircuitdesign.com/open_pdks - Git at Google

 1.
 Open Galaxy
 ------------
 Welcome to Open Galaxy, the efabless.com platform for analog and digital integrated circuit design.  Open Galaxy is a cluster of CentOS virtual machines set up with applications for creating circuit schematics and layout, and running circuit simulations, verification, and characterization.  This is where efabless.com users go to design and test their circuits before placing them in the efabless Marketplace, or submitting them to a circuit design challenge.

 Help is always available on the efabless.com website.  Just go to the dashboard, then select 'Learn and Practice'.  The select from the menu 'Community', then 'Knowledge Base'.

 1.1
 Open Galaxy Project Manager
 ------------
 This application is the project manager for Open Galaxy.  It can be used to handle imported files and challenges from the efabless.com Marketplace, create new circuit design projects and set them up for the design flow, and launch the various applications for circuit design and layout.

 1.2
 The Project Manager Window
 --------------
 The Open Galaxy Project Manager consists of four main windows.  From top to bottom, these are:
 (1) User information, showing the user's log-in name on the efabless.com website;
 (2) Projects Window
 (3) Imports Window
 (4) Message window with any messages reported by the system.

 1.3
 The Projects Window
 --------------
 The Projects window shows all of the subfolders of the user's 'design' folder.  To select a project as the 'current project', just click on the line in the projects window, and the current project will be highlighted.

 There are three columns shown in the projects window:

 (1) The name of the project.  This is determined by the 'ip-name' given in the project's JSON file, if it has one;  otherwise, it is the name of the sub-folder.
 (2) The full path to the project.
 (3) The PDK (process design kit) assigned to the project, if any.

 Below the display of project names is a row of buttons:

 "Delete":  Deletes an entire project from the project folder.  Use this with caution.  To prevent accidental deletion, the user must confirm the delete in a popup window by selecting a checkbox and then clicking 'Okay'.

 "Create":  Creates a new project and seeds it with a basic setup for project work.  The user is prompted for a project name as well as a PDK to apply to the project.  The project setup includes links to the PDK for schematic entry, which makes the PDK components available to the user for building schematics.  When there are no projects in the user's project folder, this is the only button available.

 "Copy":  Copies an entire project into a new project space.  The user is prompted for a name for the new project.  The new project retains the PDK of the original, as well as all files.  However, by default, simulation results and schematic tool preferences are not copied into the new project.  Either of these can be overridden by selecting the appropriate checkbox in the copy project dialog.

 "Clean":  Removes all simulation data from a project.  This cleans up the large files typically produced during simulations.  It does not affect any other files in the project.

 A second row of buttons is for launching applications for creating a design.

 "Edit Schematic":  Starts the 'Electric' schematic editor.

 "Edit Layout":  This button is active only if the PDK supports layout.  It starts the 'Magic' layout editor.

 "Characterize":  Starts the characterization tool, which runs local simulations on a netlist defined by a challenge, and allows a completed and simulated design to be submitted to the challenge.  The characterization application has its own help window.

 1.4
 The Imports Window
 --------------
 The Imports window shows all of the items in the 'import' subfolder of the user's 'design' folder.  This location is where all items imported into Open Galaxy from the efabless Marketplace show up, including accepted challenges, netlists from 'IP Upload', and netlists from the cloudv service.  When a file is in the import folder, three buttons are shown below the imports window:

 (1) "Import As" will move the file from the import folder to a project.  If the import is from a challenge, then the PDK is specified, as is the project name.  The import will happen automatically unless there is already a project by the same name, in which case there will be a prompt for a new name.  If the import is a simple netlist, then a project name and PDK will be requested, and a new project will be created for the netlist file.

 (2) "Import Into" will move the file, if it is a simple netlist, into an existing project.  If the import represents an entire project, for example, a challenge, then this button behaves the same as "Import As".

 (3) "Delete" will remove a file from the import folder.

 When a file is successfully transferred from the import folder to a project, it is removed from the import folder.

 2.
 Files and Folders
 ----------
 The users's primary workspace

 2.1
 User account
 ------------
 The user is given an Open Galaxy account which has a randomly assigned username unique to the user.  When running the project manager or characterization tools, the user's efabless account login name will be queried and displayed.  However, the actual home directory of the user is in the file system path '/home/username', whre 'username' is the unique Open Galaxy assigned name;  and the workspace is in the sub-folder 'design/' of the home directory.  Projects are all sub-folders of the 'design/' path.

 2.2
 Project
 ----------
 A project folder generally contains the following:
 (1) A JSON file that describes the project.  This file is required for challenges and should not be modified by the user, or else it may become impossible to upload the project.
 (2) Subfolder "elec", where all data used by the 'Electric' schematic editor are found.
 (3) Subfolder "spi", where the netlisted output of a schematic is placed.  A challenge design must be netlisted and its netlist placed in this folder before a challenge can be characterized or submitted to the challenge.
 (4) Subfolder "ngspice", where simulation data are placed.
 (5) Subfolder "testbench", where netlists used by the characterization are found.  These netlists are downloaded with the rest of the challenge data when the challenge is accepted.  The user may alter the netlists, but doing so may result in different simulation results than are used to judge the challenge submissions.
 (6) Subfolder "mag", where layout data are placed when editing layout.

 3.
 Challenges
 -----------
 A major aspect of the efabless platform is the Challenge, a way to encourage the generation of IP for the Marketplace by having a contest to create some specific design.  The Challenge is based on a Datasheet, which contains all the information about the critical properties and limits of a circuit.  Challenges are issued from time to time on the efabless website.

 To participate in a Challenge, go to the efabless website and log in as an efabless user.  Navigate to the Marketplace.  There you should see an icon labeled 'Open Challenges'.  Click on this icon to navigate to the Challenges page.

 On the Challenges page, scroll to the bottom of the page to find a list of "Open Projects".  Clock on the Project Title to see what the challenge is about.  To join the challenge, simply click on "Apply" next to the challenge.  This will bring up a complete view of the challenge.  Click "Accept" to accept the challenge, and finally, "Confirm" to accept the terms and conditions of the challenge.  This final step will initiate a download of challenge files into your Open Galaxy workspace.

 3.1
 Importing a Challenge
 -----------
 After a challenge has been accepted in the marketplace, a new entry will appear in 'Imports' containing the files needed to start the challenge design.  Select the project and press the 'Import' button to create and populate your design folder with the new project.  The new project will then appear under the 'Projects' list.  The new project will be set up with the PDK (process design kit) specified for the challenge, and will already contain a schematic symbol for the project circuit showing all of the required pins.

 3.2
 Creating a Challenge Design
 ------------
 The first step of creating a challenge design is to select the challenge project in the Projects window, and click on "Edit Schematic" to start the "Electric" schematic editor.  The editor should immediately display the symbol of the challenge circuit.  This symbol has all the pins of the challenge device, and should not be altered.  Create a new schematic to match the symbol by selecting "View"->"Create Schematic View" in the menu.  Components of the PDK are available in the "Components" tab on the left.  For information about using Electric to edit a schematic, refer to the Electric "Help" menu.

 3.3
 Simulating a Challenge
 ----------------
 The user has all the resources of Electric to simulate and display results.  Refer to the Electric user manual in the "Help" menu of Electric.  However, the user will want to know how the circuit behaves relative to the specifications required by the challenge.  To do this, first create a netlist of the schematic in Electric using menu selection "Tools"->"Simulation (Spice)"->"Write CDL Deck".  Once the netlist is written, the user may return to the project manager and click the "Characterize" button.  Note that the "Characterize" button is disabled unless both the challenge's project JSON file and the netlist file created from Electric exist.  For information on using the Open Galaxy characterization application, see the help text in the application.
 .
	1.
	Open Galaxy
	------------
	Welcome to Open Galaxy, the efabless.com platform for analog and digital integrated circuit design. Open Galaxy is a cluster of CentOS virtual machines set up with applications for creating circuit schematics and layout, and running circuit simulations, verification, and characterization. This is where efabless.com users go to design and test their circuits before placing them in the efabless Marketplace, or submitting them to a circuit design challenge.

	Help is always available on the efabless.com website. Just go to the dashboard, then select 'Learn and Practice'. The select from the menu 'Community', then 'Knowledge Base'.

	1.1
	Open Galaxy Project Manager
	------------
	This application is the project manager for Open Galaxy. It can be used to handle imported files and challenges from the efabless.com Marketplace, create new circuit design projects and set them up for the design flow, and launch the various applications for circuit design and layout.

	1.2
	The Project Manager Window
	--------------
	The Open Galaxy Project Manager consists of four main windows. From top to bottom, these are:
	(1) User information, showing the user's log-in name on the efabless.com website;
	(2) Projects Window
	(3) Imports Window
	(4) Message window with any messages reported by the system.

	1.3
	The Projects Window
	--------------
	The Projects window shows all of the subfolders of the user's 'design' folder. To select a project as the 'current project', just click on the line in the projects window, and the current project will be highlighted.

	There are three columns shown in the projects window:

	(1) The name of the project. This is determined by the 'ip-name' given in the project's JSON file, if it has one; otherwise, it is the name of the sub-folder.
	(2) The full path to the project.
	(3) The PDK (process design kit) assigned to the project, if any.

	Below the display of project names is a row of buttons:

	"Delete": Deletes an entire project from the project folder. Use this with caution. To prevent accidental deletion, the user must confirm the delete in a popup window by selecting a checkbox and then clicking 'Okay'.

	"Create": Creates a new project and seeds it with a basic setup for project work. The user is prompted for a project name as well as a PDK to apply to the project. The project setup includes links to the PDK for schematic entry, which makes the PDK components available to the user for building schematics. When there are no projects in the user's project folder, this is the only button available.

	"Copy": Copies an entire project into a new project space. The user is prompted for a name for the new project. The new project retains the PDK of the original, as well as all files. However, by default, simulation results and schematic tool preferences are not copied into the new project. Either of these can be overridden by selecting the appropriate checkbox in the copy project dialog.

	"Clean": Removes all simulation data from a project. This cleans up the large files typically produced during simulations. It does not affect any other files in the project.

	A second row of buttons is for launching applications for creating a design.

	"Edit Schematic": Starts the 'Electric' schematic editor.

	"Edit Layout": This button is active only if the PDK supports layout. It starts the 'Magic' layout editor.

	"Characterize": Starts the characterization tool, which runs local simulations on a netlist defined by a challenge, and allows a completed and simulated design to be submitted to the challenge. The characterization application has its own help window.

	1.4
	The Imports Window
	--------------
	The Imports window shows all of the items in the 'import' subfolder of the user's 'design' folder. This location is where all items imported into Open Galaxy from the efabless Marketplace show up, including accepted challenges, netlists from 'IP Upload', and netlists from the cloudv service. When a file is in the import folder, three buttons are shown below the imports window:

	(1) "Import As" will move the file from the import folder to a project. If the import is from a challenge, then the PDK is specified, as is the project name. The import will happen automatically unless there is already a project by the same name, in which case there will be a prompt for a new name. If the import is a simple netlist, then a project name and PDK will be requested, and a new project will be created for the netlist file.

	(2) "Import Into" will move the file, if it is a simple netlist, into an existing project. If the import represents an entire project, for example, a challenge, then this button behaves the same as "Import As".

	(3) "Delete" will remove a file from the import folder.

	When a file is successfully transferred from the import folder to a project, it is removed from the import folder.

	2.
	Files and Folders
	----------
	The users's primary workspace

	2.1
	User account
	------------
	The user is given an Open Galaxy account which has a randomly assigned username unique to the user. When running the project manager or characterization tools, the user's efabless account login name will be queried and displayed. However, the actual home directory of the user is in the file system path '/home/username', whre 'username' is the unique Open Galaxy assigned name; and the workspace is in the sub-folder 'design/' of the home directory. Projects are all sub-folders of the 'design/' path.

	2.2
	Project
	----------
	A project folder generally contains the following:
	(1) A JSON file that describes the project. This file is required for challenges and should not be modified by the user, or else it may become impossible to upload the project.
	(2) Subfolder "elec", where all data used by the 'Electric' schematic editor are found.
	(3) Subfolder "spi", where the netlisted output of a schematic is placed. A challenge design must be netlisted and its netlist placed in this folder before a challenge can be characterized or submitted to the challenge.
	(4) Subfolder "ngspice", where simulation data are placed.
	(5) Subfolder "testbench", where netlists used by the characterization are found. These netlists are downloaded with the rest of the challenge data when the challenge is accepted. The user may alter the netlists, but doing so may result in different simulation results than are used to judge the challenge submissions.
	(6) Subfolder "mag", where layout data are placed when editing layout.

	3.
	Challenges
	-----------
	A major aspect of the efabless platform is the Challenge, a way to encourage the generation of IP for the Marketplace by having a contest to create some specific design. The Challenge is based on a Datasheet, which contains all the information about the critical properties and limits of a circuit. Challenges are issued from time to time on the efabless website.

	To participate in a Challenge, go to the efabless website and log in as an efabless user. Navigate to the Marketplace. There you should see an icon labeled 'Open Challenges'. Click on this icon to navigate to the Challenges page.

	On the Challenges page, scroll to the bottom of the page to find a list of "Open Projects". Clock on the Project Title to see what the challenge is about. To join the challenge, simply click on "Apply" next to the challenge. This will bring up a complete view of the challenge. Click "Accept" to accept the challenge, and finally, "Confirm" to accept the terms and conditions of the challenge. This final step will initiate a download of challenge files into your Open Galaxy workspace.

	3.1
	Importing a Challenge
	-----------
	After a challenge has been accepted in the marketplace, a new entry will appear in 'Imports' containing the files needed to start the challenge design. Select the project and press the 'Import' button to create and populate your design folder with the new project. The new project will then appear under the 'Projects' list. The new project will be set up with the PDK (process design kit) specified for the challenge, and will already contain a schematic symbol for the project circuit showing all of the required pins.

	3.2
	Creating a Challenge Design
	------------
	The first step of creating a challenge design is to select the challenge project in the Projects window, and click on "Edit Schematic" to start the "Electric" schematic editor. The editor should immediately display the symbol of the challenge circuit. This symbol has all the pins of the challenge device, and should not be altered. Create a new schematic to match the symbol by selecting "View"->"Create Schematic View" in the menu. Components of the PDK are available in the "Components" tab on the left. For information about using Electric to edit a schematic, refer to the Electric "Help" menu.

	3.3
	Simulating a Challenge
	----------------
	The user has all the resources of Electric to simulate and display results. Refer to the Electric user manual in the "Help" menu of Electric. However, the user will want to know how the circuit behaves relative to the specifications required by the challenge. To do this, first create a netlist of the schematic in Electric using menu selection "Tools"->"Simulation (Spice)"->"Write CDL Deck". Once the netlist is written, the user may return to the project manager and click the "Characterize" button. Note that the "Characterize" button is disabled unless both the challenge's project JSON file and the netlist file created from Electric exist. For information on using the Open Galaxy characterization application, see the help text in the application.
	.